GET /rest/v1/users

Implementation notes

Handles the GET request of retrieving all users within Bosch IoT Rollouts. Required permission: USER_MANAGEMENT

Get paged list of users

CURL

$ curl 'https://management-api.host.com/rest/v1/users?offset=1&limit=2&sort=name%3ADESC&q=name%3D%3Ddocu*' -i -X GET

Request URL

A GET request is used to access the targets

GET /rest/v1/users?offset=1&limit=2&sort=name%3ADESC&q=name%3D%3Ddocu* HTTP/1.1
Host: management-api.host.com

Request query parameter

Parameter Description

limit

The maximum number of entries in a page (default is 50).

sort

The query parameter sort allows to define the sort order for the result of a query. A sort criteria consists of the name of a field and the sort direction (ASC for ascending and DESC descending). The sequence of the sort criteria (multiple can be used) defines the sort order of the entities in the result.

offset

The paging offset (default is 0).

q

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for available fields.

Request parameter example

GET /rest/v1/users?offset=1&limit=2&sort=name%3ADESC&q=name%3D%3Ddocu* HTTP/1.1
Host: management-api.host.com

Response (Status 200)

Response fields

Path Type Description Allowed Values

total

Number

Total number of elements

size

Number

Current page size

content

Array

List of users

content[].id

Number

The technical identifier of the user

content[].name

String

The email-address of the user

content[].systemManaged

Boolean

The type of the user

content[]._links.permissions.href

String

Link to list of permissions of the role

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 682

{
  "content" : [ {
    "name" : "docu_user2@bosch.com",
    "systemManaged" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/users/16"
      },
      "permissions" : {
        "href" : "https://management-api.host.com/rest/v1/users/16/permissions"
      }
    },
    "id" : 16
  }, {
    "name" : "docu_user@bosch.com",
    "systemManaged" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/users/15"
      },
      "permissions" : {
        "href" : "https://management-api.host.com/rest/v1/users/15/permissions"
      }
    },
    "id" : 15
  } ],
  "total" : 3,
  "size" : 2
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

POST /rest/v1/users

Implementation Notes

Handles the POST request of creating new users within Bosch IoT Rollouts. The request body must always be a list of users. Required Permission: USER_MANAGEMENT

Create list of users

CURL

$ curl 'https://management-api.host.com/rest/v1/users' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '[ {
  "name" : "new_user@bosch.com"
} ]'

Request URL

POST /rest/v1/users HTTP/1.1
Content-Type: application/json
Content-Length: 39
Host: management-api.host.com

[ {
  "name" : "new_user@bosch.com"
} ]

Request fields

Path Type Description Allowed Values Mandatory

[]name

String

The email-address of the user

X

Response (Status 201)

Response fields

Path Type Description Allowed Values

[]name

String

The email-address of the user

[]id

Number

The description of the entity

[]systemManaged

Boolean

The type of the user

Response example

HTTP/1.1 201 Created
Content-Type: application/hal+json
Content-Length: 293

[ {
  "name" : "new_user@bosch.com",
  "systemManaged" : false,
  "links" : [ {
    "rel" : "self",
    "href" : "https://management-api.host.com/rest/v1/users/9"
  }, {
    "rel" : "permissions",
    "href" : "https://management-api.host.com/rest/v1/users/9/permissions"
  } ],
  "id" : 9
} ]

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, data volume restriction applies or quota limit exceeded.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request.

See Error body

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

DELETE /rest/v1/users/{userId}

Implementation Notes

Handles the DELETE request of deleting a single user within Bosch IoT Rollouts. Required Permission: USER_MANAGEMENT

Deleting a target

CURL

$ curl 'https://management-api.host.com/rest/v1/users/27' -i -X DELETE \
    -H 'Content-Type: application/json'

Request URL

DELETE /rest/v1/users/27 HTTP/1.1
Content-Type: application/json
Host: management-api.host.com

Request path parameter

Parameter Description

userId

The technical identifier of the user

Response (Status 200)

Response example

HTTP/1.1 200 OK

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/users/{userId}

Implementation Notes

Handles the GET request of retrieving a single user within Bosch IoT Rollouts. Required Permission: USER_MANAGEMENT

Get single user

CURL

$ curl 'https://management-api.host.com/rest/v1/users/19' -i -X GET

Request URL

GET /rest/v1/users/19 HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

userId

The technical identifier of the user

Response (Status 200)

Response fields

Path Type Description Allowed Values

id

Number

The technical identifier of the user

name

String

The email-address of the user

systemManaged

Boolean

The type of the user

_links.permissions.href

String

Link to list of permissions of the user

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 290

{
  "name" : "docu_user@bosch.com",
  "systemManaged" : false,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/users/19"
    },
    "permissions" : {
      "href" : "https://management-api.host.com/rest/v1/users/19/permissions"
    }
  },
  "id" : 19
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/users/{userId}/permissions

Implementation Notes

Handles the GET request of retrieving the permissions list of a specific user. Required Permission: USER_MANAGEMENT

List all permissions of a user

Curl

$ curl 'https://management-api.host.com/rest/v1/users/23/permissions' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json'

Request URL

GET /rest/v1/users/23/permissions HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Host: management-api.host.com

Request path parameter

Parameter Description

userId

The technical identifier of the user

Request parameter example

GET /rest/v1/users/23/permissions HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Host: management-api.host.com

Response (Status 200)

Response fields

Path Type Description Allowed Values

[]

Array

list of user permissions

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 68

[ "DELETE_TARGET", "READ_TARGET", "CREATE_TARGET", "UPDATE_TARGET" ]

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

POST /rest/v1/users/{userId}/permissions

Implementation Notes

Handles the POST request to add grant permissions to a user. Required Permission: USER_MANAGEMENT

Grant permission to a target

Curl

$ curl 'https://management-api.host.com/rest/v1/users/11/permissions' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '[ "READ_REPOSITORY", "CREATE_REPOSITORY", "UPDATE_REPOSITORY", "DELETE_REPOSITORY" ]'

Request URL

POST /rest/v1/users/11/permissions HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Content-Length: 84
Host: management-api.host.com

[ "READ_REPOSITORY", "CREATE_REPOSITORY", "UPDATE_REPOSITORY", "DELETE_REPOSITORY" ]

Request path parameter

Parameter Description

userId

The technical identifier of the user

Request fields

Path Type Description Allowed Values Mandatory

[]

Array

List of permissions

X

Response (Status 200)

Response fields

Path Type Description Allowed Values

[]

Array

list of role permissions

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 150

[ "READ_REPOSITORY", "DELETE_TARGET", "UPDATE_REPOSITORY", "READ_TARGET", "CREATE_TARGET", "UPDATE_TARGET", "DELETE_REPOSITORY", "CREATE_REPOSITORY" ]

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request.

See Error body

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

DELETE /rest/v1/users/{userId}/permissions/{permission}

Implementation Notes

Handles the DELETE request of removing permissions from a user. Required Permission: USER_MANAGEMENT

Canceling an active action

Curl

$ curl 'https://management-api.host.com/rest/v1/users/2/permissions/DELETE_REPOSITORY' -i -X DELETE \
    -H 'Accept: application/hal+json'

Request URL

DELETE /rest/v1/users/2/permissions/DELETE_REPOSITORY HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com

Request path parameter

Parameter Description

userId

The technical identifier of the user

permission

The type of the permission

Response (Status 200)

Response fields

Path Type Description Allowed Values

[]

Array

list of role permissions

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 68

[ "DELETE_TARGET", "READ_TARGET", "CREATE_TARGET", "UPDATE_TARGET" ]

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

Additional content

Error body

{
  "errorCode": "string",
  "exceptionClass": "string",
  "message": "string",
  "parameters": [
    "string"
  ]
}

Field description

Field

Description

errorCode

A error code/key set by server

exceptionClass

The involved exceptionClass

message

An error message set by the server

parameters

A list of parameters

© Bosch.IO GmbH, all rights reserved Corporate information | Data protection notice | Legal information | Support | Free plans