Credentials management service REST 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 post
get

Returns a JSON representation of the provisioned endpoint tokens.

post

Provisions a new endpoint token.

Returns a JSON representation of the provisioned endpoint tokens.

Secured by oauth_2_0 with scopes:
  • 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: (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: (array of string - minItems: 0)

    Filters results by the endpoint token statuses.

    Example:

    [
  "Inactive",
  "Active",
  "Suspended",
  "Revoked"
]
  • offset: (integer)

    The starting index from which the server should return data.

    Example:

    10
  • limit: (integer - default: 20)

    The maximum number of items to be returned.

    Example:

    2
  • order: (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 cm-api-types.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: (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"
}
    • 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.

    Provisions a new endpoint token.

    Secured by oauth_2_0 with scopes:
    • 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: (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 to Active 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 delete

    Single endpoint token operations

    get

    Returns endpoint token information.

    delete

    Deletes an endpoint token.

    Returns endpoint token information.

    Secured by oauth_2_0 with scopes:
    • 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: (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: (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.

      Deletes an endpoint token.

      Secured by oauth_2_0 with scopes:
      • 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 put
      get

      Returns the current status of the endpoint token.

      put

      Sets the current endpoint token status. Allowed status transitions are:

      • `Active` → `Suspended`
      • `Suspended` → `Active`
      • Any status → `Revoked`

      Returns the current status of the endpoint token.

      Secured by oauth_2_0 with scopes:
      • 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: (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.

        Sets the current endpoint token status. Allowed status transitions are:

        • `Active` → `Suspended`
        • `Suspended` → `Active`
        • Any status → `Revoked`
        Secured by oauth_2_0 with scopes:
        • 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.