Only authenticated requests to the REST API will be processed. This authentication process serves the following two purposes:
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.
api.transactcdn.com
Requests to api.transactcdn.com leverage a REST API token.
Please contact your TCC administrator to request access to our REST API service. Upon approval, you will be allowed to generate and view tokens.
API Gateway (api.vdms.io)
Requests to our API gateway require a token generated from your OAuth 2.0 credentials. By default, this type of token expires after 300 seconds.
Register your client application via the VDMS Identity dashboard to generate OAuth 2.0 credentials through which you may authorize requests submitted to our API gateway (api.vdms.io).
This section explains:
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.
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:
TCC Administrator: A TCC administrator defines each user's level of access to the REST API.
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:
Navigate to the Settings page.
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.
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.
Setting up REST API request authentication requires setting the Authorization request header to your REST API token using the following syntax:
Key information:
A request will not be authorized under the following conditions:
An unauthorized request will generate a 403 Forbidden response. The response body may indicate the reason why the request was deemed unauthorized (e.g., an invalid user was specified).
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
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:
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.
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.
API Request
The client application must then pass this access token via an Authorization header when submitting a request to our REST API.
API Response
If the access token authorizes the requested action, then our REST API service will process it.
This workflow is illustrated below.
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:
Secret: This value authenticates the client application identified above.
Do not expose the secret assigned to your account, since it may be used to impersonate your client application. For example, do not define your secret within a client-side script.
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:
Requests for access tokens requires a Content-Type header set to application/x-www-form-urlencoded.
Set the request body to:
client_id=Client IDRepresents the system-defined ID assigned to your REST API client.&client_secret=SecretRepresents the secret assigned to your REST API client.&grant_type=client_credentials&scope=ScopesReplace this term with one or more scopes. Use the plus symbol (+) to delimit each scope.
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" }
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:
Key information:
An unauthorized request will generate a 401 Unauthorized response. The response body may indicate the reason why the request was deemed unauthorized. A request will not be authorized under the following conditions:
A sample Authorization request header is provided below.