Here is
new documentation version.
You are reading outdated documentation, which will be shutdown soon!
REST API
Credentials management service REST API documentation version v1
{schema}://{host}/api/{version}
- schema: required(one of http, https - default: http)
- host: required(string - default: localhost)
- version: required(v1)
Endpoint tokens
Operations on endpoint tokens
get /endpoints/{endpointId}/tokens
Returns a JSON representation of the provisioned endpoint tokens.
- endpoint:read
CM supports OAuth 2.0 for authenticating all API requests.
URI Parameters
- endpointId: required(string)
Identifies the endpoint to which operations with an endpoint token are applied.
Example:
7d5dda9b-c9f6-427d-91ea-9891a4f62cbb
Headers
- If-None-Match: optional (string)
Makes the request conditional.
The server will send the requested endpoint tokens with `200` status only if current `ETag` value doesn't match the specified one.
Otherwise, `304 Not Modified` status will be returned.Example:
"33a64df551425fcc55e4d42a148795d9f25f89d4"
Query Parameters
- status: optional (array of EndpointTokenStatuses)
Filters results by the endpoint token statuses.
Example:
[ "Inactive", "Active", "Suspended", "Revoked" ]
- offset: optional (integer)
The starting index from which the server should return data.
Example:
10
- limit: optional (integer - default: 20)
The maximum number of items to be returned.
Example:
2
- order: optional (one of ASC, DESC - default: DESC)
The sorting order of returned tokens (from the newest to the oldest and vice versa).
Example:
ASC
HTTP status code 200
An array of the endpoint token objects.
Headers
- ETag: required(string)
Represents the current endpoint tokens state.
The value can be used in `If-Match` and `If-None-Match` headers.
Example:
"33a64df551425fcc55e4d42a148795d9f25f89d4"
Body
Media type: application/json
Type: object
Properties
- content: required(array of EndpointTokenArrayItem)
Array of endpoint tokens with details.
Items: EndpointTokenArrayItem
- status: required(one of Active, Inactive, Suspended, Revoked)
The status of the endpoint token.
- `Inactive` - the token was never used
- `Active` - the token was already used
- `Suspended` - frozen token
- `Revoked` - canceled token
- endpointTokenId: required(string)
Endpoint token ID.
- createdDate: required(datetime)
Token creation (provisioning) time and date in ISO 8601 format.
- applicationName: required(string)
The application name.
- updatedDate: optional (datetime)
The token change status last time and date in ISO 8601 format
Example:
{ "endpointTokenId": "33a64df551425fcc55e4d42a148795d9f25f89d4", "applicationName": "smart_kettle", "createdDate": "2017-03-17T11:30:02.643Z", "status": "Active", "updatedDate": "2017-03-17T12:00:01.311Z" }
- status: required(one of Active, Inactive, Suspended, Revoked)
- totalElements: required(integer)
The total number of tokens available for this request (ignoring pagination).
Example:
{
"content": [
{
"endpointTokenId": "33a64df551425fcc55e4d42a148795d9f25f89d4",
"applicationName": "smart_kettle",
"createdDate": "2017-03-17T11:30:02.643Z",
"status": "Inactive",
"updatedDate": "2017-03-17T12:00:01.311Z"
},
{
"endpointTokenId": "78a64pf846395kcc55e4d42a148795d9f25f89d4",
"applicationName": "smart_kettle",
"createdDate": "2017-03-17T11:30:02.643Z",
"status": "Active",
"updatedDate": "2017-03-17T12:00:01.311Z"
}
],
"totalElements": 7
}
HTTP status code 304
Resource(s) not modified.
HTTP status code 404
The endpoint ID was not found..
Body
Media type: application/json
Type: object
Properties
- message: required(string)
Detailed error description.
Secured by oauth_2_0
Headers
- Authorization: required(string)
Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by valid OAuth access token.
post /endpoints/{endpointId}/tokens
Provisions a new endpoint token.
- endpoint:update
CM supports OAuth 2.0 for authenticating all API requests.
URI Parameters
- endpointId: required(string)
Identifies the endpoint to which operations with an endpoint token are applied.
Example:
7d5dda9b-c9f6-427d-91ea-9891a4f62cbb
Body
Media type: application/json
Type: object
Properties
- token: optional (string - pattern: ^[^+#/.]+$)
Endpoint token. Will be generated if not present.
Must not contain plus signs (`+`), number signs (`#`), forward slashes (`/`), or periods (`.`).
- applicationName: required(string)
The application name.
Example:
{
"token": "02226466-e744-48ac-8f0c-a57fe4e77de4",
"applicationName": "sample-application-1"
}
HTTP status code 201
The endpoint token was successfully provisioned.
Headers
- Location: required(string)
The URL to access a newly created endpoint token.
Example:
http://example.com/api/v1/endpoints/e5ec0201-bdaa-4957-93dd-60238096f4c7/tokens/33a64df551425fcc55e4d42a148795d9f25f89d4
Body
Media type: application/json
Type: object
Properties
- token: required(string)
Endpoint token.
- createdDate: required(datetime)
Token creation (provisioning) time and date in ISO 8601 format.
- applicationName: required(string)
The application name.
- status: required(Inactive)
Status of newly provisioned token is always
Inactive
.
Token status will be automatically changed toActive
after first successful token validation request.
Example:
{
"token": "02226466-e744-48ac-8f0c-a57fe4e77de4",
"applicationName": "sample-application-1",
"createdDate": "2017-03-17T11:30:02.643Z",
"status": "Inactive"
}
HTTP status code 400
An unknown application name.
Body
Media type: application/json
Type: object
Properties
- message: required(string)
Detailed error description.
HTTP status code 409
A conflict has occured.
Body
Media type: application/json
Type: object
Properties
- message: required(string)
Detailed error description.
Example:
The endpoint token already exists.:
{
"message": "Endpoint token already exists."
}
Secured by oauth_2_0
Headers
- Authorization: required(string)
Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by valid OAuth access token.
get /endpoints/{endpointId}/tokens/{endpointTokenId}
Returns endpoint token information.
- endpoint:read
CM supports OAuth 2.0 for authenticating all API requests.
URI Parameters
- endpointId: required(string)
Identifies the endpoint to which operations with an endpoint token are applied.
Example:
7d5dda9b-c9f6-427d-91ea-9891a4f62cbb
- endpointTokenId: required(string)
An endpoint token ID to operate on.
Example:
33a64df551425fcc55e4d42a148795d9f25f89d4
Headers
- If-None-Match: optional (string)
Makes the request conditional.
The server will send the requested endpoint token with `200` status only if current `ETag` value doesn't match the specified one.
Otherwise, `304 Not Modified` status will be returned.Example:
"33a64df551425fcc55e4d42a148795d9f25f89d4"
HTTP status code 200
Endpoint token.
Headers
- ETag: required(string)
Represents the current endpoint token state.
The value can be used in `If-Match` and `If-None-Match` headers.
Example:
"33a64df551425fcc55e4d42a148795d9f25f89d4"
Body
Media type: application/json
Type: object
Properties
- status: required(one of Active, Inactive, Suspended, Revoked)
The status of the endpoint token.
- `Inactive` - the token was never used
- `Active` - the token was already used
- `Suspended` - frozen token
- `Revoked` - canceled token
- createdDate: required(datetime)
Token creation (provisioning) time and date in ISO 8601 format.
- applicationName: required(string)
The application name.
- updatedDate: optional (datetime)
Last time when the tiken was changed status in ISO 8601 format.
Example:
{
"applicationName": "smart_kettle",
"createdDate": "2017-03-17T11:30:02.643Z",
"status": "Active",
"updatedDate": "2017-03-17T12:00:01.311Z"
}
HTTP status code 304
Resource(s) not modified.
HTTP status code 404
Either the endpoint ID or the endpoint token ID was not found or user does not have permissions to perform this operation.
Body
Media type: application/json
Type: object
Properties
- message: required(string)
Detailed error description.
Secured by oauth_2_0
Headers
- Authorization: required(string)
Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by valid OAuth access token.
delete /endpoints/{endpointId}/tokens/{endpointTokenId}
Deletes an endpoint token.
- endpoint:update
CM supports OAuth 2.0 for authenticating all API requests.
URI Parameters
- endpointId: required(string)
Identifies the endpoint to which operations with an endpoint token are applied.
Example:
7d5dda9b-c9f6-427d-91ea-9891a4f62cbb
- endpointTokenId: required(string)
An endpoint token ID to operate on.
Example:
33a64df551425fcc55e4d42a148795d9f25f89d4
HTTP status code 204
The endpoint token was successfully deleted.
HTTP status code 404
Either the endpoint ID or the endpoint token ID was not found or user does not have permissions to perform this operation.
Body
Media type: application/json
Type: object
Properties
- message: required(string)
Detailed error description.
Secured by oauth_2_0
Headers
- Authorization: required(string)
Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by valid OAuth access token.
get /endpoints/{endpointId}/tokens/{endpointTokenId}/status
Returns the current status of the endpoint token.
- endpoint:read
CM supports OAuth 2.0 for authenticating all API requests.
URI Parameters
- endpointId: required(string)
Identifies the endpoint to which operations with an endpoint token are applied.
Example:
7d5dda9b-c9f6-427d-91ea-9891a4f62cbb
- endpointTokenId: required(string)
An endpoint token ID to operate on.
Example:
33a64df551425fcc55e4d42a148795d9f25f89d4
Headers
- If-None-Match: optional (string)
Makes the request conditional.
The server will send the requested endpoint token status with `200` status only if current `ETag` value doesn't match the specified one.
Otherwise, `304 Not Modified` status will be returned.Example:
"33a64df551425fcc55e4d42a148795d9f25f89d4"
HTTP status code 200
Headers
- ETag: required(string)
Represents the current endpoint token status state.
The value can be used in `If-Match` and `If-None-Match` headers.
Example:
"33a64df551425fcc55e4d42a148795d9f25f89d4"
Body
Media type: application/json
Type: object
Properties
- status: required(one of Active, Inactive, Suspended, Revoked)
The status of the endpoint token.
- `Inactive` - the token was never used
- `Active` - the token was already used
- `Suspended` - frozen token
- `Revoked` - canceled token
Example:
{
"status": "Active"
}
HTTP status code 304
Resource(s) not modified.
HTTP status code 404
Either the endpoint ID or the endpoint token ID was not found or user does not have permissions to perform this operation.
Body
Media type: application/json
Type: object
Properties
- message: required(string)
Detailed error description.
Secured by oauth_2_0
Headers
- Authorization: required(string)
Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by valid OAuth access token.
put /endpoints/{endpointId}/tokens/{endpointTokenId}/status
Sets the current endpoint token status. Allowed status transitions are:
- `Active` → `Suspended`
- `Suspended` → `Active`
- Any status → `Revoked`
- endpoint:update
CM supports OAuth 2.0 for authenticating all API requests.
URI Parameters
- endpointId: required(string)
Identifies the endpoint to which operations with an endpoint token are applied.
Example:
7d5dda9b-c9f6-427d-91ea-9891a4f62cbb
- endpointTokenId: required(string)
An endpoint token ID to operate on.
Example:
33a64df551425fcc55e4d42a148795d9f25f89d4
Body
Media type: application/json
Type: object
Properties
- status: required(one of Active, Suspended, Revoked)
The status of the endpoint token.
- `Active` - the token was already used
- `Suspended` - frozen token
- `Revoked` - canceled token
Example:
{
"status": "Active"
}
HTTP status code 204
The endpoint token status was successfully changed.
HTTP status code 400
An invalid status or such a change is forbidden.
Body
Media type: application/json
Type: object
Properties
- message: required(string)
Detailed error description.
HTTP status code 404
Either the endpoint ID or the endpoint token ID was not found or user does not have permissions to perform this operation.
Body
Media type: application/json
Type: object
Properties
- message: required(string)
Detailed error description.
Secured by oauth_2_0
Headers
- Authorization: required(string)
Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by valid OAuth access token.