Authentication and Authorization

Only authenticated requests to the REST API will be processed. This authentication process serves the following two purposes:

  1. Identifies the user making the request.
  2. Verifies that the user making the request has sufficient permissions to perform the requested action.

User authentication requires passing a unique value (i.e., token). The type of token that may be used to authenticate your requests varies according to whether the service is hosted on our API gateway.

This section explains:

REST API Token

Use OAuth 2.0 credentials to authorize requests to endpoints hosted on our API gateway (api.vdms.io). Requests to these endpoints cannot be authorized via a REST API token.
Learn more.

A REST API token is a unique alphanumeric value that identifies the user account through which the requested task will be performed. This ensures that only endpoints that have been authorized for that user account will be successfully completed.

A sample token value is shown below.

12345678-1234-1234-1234-1234567890ab

Viewing a Token

A REST API token is required to authenticate a REST API request. Generate and view your unique token(s) from the Web Services REST API Token section of the Settings page.

Key information:

Generating a Token

As a best practice, the REST API token should be updated at regular intervals.

The recommended method for updating a REST API token involves the following steps:

  1. Navigate to the Settings page.

  2. Click Edit.
  3. Click Generate New Primary. When prompted, click OK to confirm this action.
  4. From your preferred email client, open the verification email and then follow the verification link. The current primary token will be set as a backup token.

    Both primary and backup tokens provide the same level of access to the REST API.

  5. Update existing applications to use the new token value.
  6. Delete the backup token.

It is highly recommended that the backup token only be used to transition your existing applications to the new primary token.

Tokens that are no longer listed on the Settings page cannot be used to authenticate to a REST API service.

Authenticating Requests

Setting up REST API request authentication requires setting the Authorization request header to your REST API token using the following syntax:

TOK: Token

Key information:

Examples

Sample Authorization request headers are provided below.

Example #1:

Authorization: TOK:12345678-1234-1234-1234-1234567890ab

Example #2:

Authorization: tok:12345678-1234-1234-1234-1234567890AB

OAuth 2.0

Authorization for our API gateway is managed by a centralized identity management solution called Identity Service (IDS). IDS leverages OAuth 2.0, which complies with the specification defined within RFC 6749, to authorize requests to the API.

Requests to our API gateway are authorized through the following workflow:

  1. Access Token Request

    A client application requests API access from IDS. This request must include authentication information and a scope that defines the type of API requests that will be authorized.

  2. Temporary Access Token

    If IDS is able to authenticate the client application, it will respond with a temporary access token set to the defined scope.

  3. API Request

    The client application must then pass this access token via an Authorization header when submitting a request to our REST API.

  4. API Response

    If the access token authorizes the requested action, then our REST API service will process it.

This workflow is illustrated below.

Registering a Client Application (Prerequisite)

Register your client application before interacting with REST API services hosted on our API gateway. Upon successfully registering your client application, the following information will be generated for your client application:

Generating Access Tokens

Each request to our REST API service must be authorized via an access token. Access tokens must be requested from IDS.

Access tokens provide temporary authorization (e.g., 5 minutes) to our REST API service. Once an access token expires, it may no longer be used to authorize requests. Attempting to authorize a request with an expired token will result in a 401 Unauthenticated Access response.

Request syntax:

POST https://id.vdms.io/connect/token

Requests for access tokens requires a Content-Type header set to application/x-www-form-urlencoded.

Set the request body to:

Set the scope request body parameter to the desired scope. Common scopes are listed below.

Scope Description

ec.rules

Authorizes full access to the Rules Engine service.

Sample request:

POST https://id.vdms.io/connect/token HTTP/1.1

Accept: application/json

Content-Type: application/x-www-form-urlencoded

Host: id.vdms.io

client_id=J23...BCdJ2345678-abcd-9012-efgh-34567890aBCd&client_secret=Fad...DFvFad323FSd4GSdce3DFv&grant_type=client_credentials&scope=ec.rules

Sample response:

HTTP/1.1 200 OK

Cache-Control: no-store, no-cache, max-age=0

Content-Type: application/json; charset=UTF-8

Date: Thu, 15 Apr 2021 12:00:00 GMT

Content-Length: 830

{
	"access_token": "A1bcbGciOiJSUzI1NiIsImtpZCI6Ij13N1VGQ01z...A1bcbGciOiJSUzI1NiIsImtpZCI6Ij13N1VGQ01zOTIzQjI1MTYzRjU4MU1wQ0I3MUNBRDk3QjAzNkUwQjgiLCJ01XAiOiJKV1QiLCJ4NXQiOiJGMDc4bzVJN0pSWV9XQm9Ndcc5dGw3QTI0TGcifQ.1yJuYmYiOj11NjUzMDgwNzgsImV4cCI6MTU2NTMwODM3OCwiaXNzIjoiacR0ccM6Ly9pZC52ZG1zLmlvIiwiYXVkIjpbImc0dcBzOi8vaWQudmRtcy5pby9yZXNvdXJjZXMiLCJlYy5ydWxlcyJdLCJjbGllbnRfaWQiOiIxNTccOWZmZi04MTQzLTRmOW1tOWY1Yi1jNDgzZWVkNzclM2QiLCJzY29wZSI6WyJlYy5ydWxlcyJdfQ.XQ4TvzDrwLo4bO71cb1TbgYxmtcgTzC46Do0A9F3inAqw1qcr_Nr9IgRDxJDqR4Udc9QR86LVTQC2-ogGWP3pI12GtDtiUQdKYs5fpcuMf2Kbqau6kuU1M5BJm_GOcBNCCAJnU7SrDprVbPlwanGqk3yjcyo9nto8KWCRTwq2t31UQ1Ci31FZSr4vaMZJqk1vBW6NS3-yGowGCZbSIQBKpSgcc75coPtSjF1Qi6M4yORDyMC8c3KKlIp2b-6mpfDFXINIFV-XvnNuQ9v-lcc43_VWuDA_cQO8wmS4VzS1Ac1tpg1Pp4Bcdtjt12yKAXvi0X19R1BDmpxmO17cRRKYQ",
	"expires_in": 300,
	"token_type": "Bearer"
}

Authorizing Requests

Requests to our API gateway must be authorized via an access token. Specify an access token within the Authorization request header when submitting a request to our REST API service.

Authorization header syntax:

Bearer Access Token

Key information:

Examples

A sample Authorization request header is provided below.