Authentication

The Architect APIs are secured using the OAuth 2.0 Client Credentials flow, which ensures that only authorized applications can access the APIs. As part of the user or system onboarding process, each API consumer is provisioned with a unique Client ID and Client Secret. These credentials are used to request an access token from the authorization server. The access token must be included in every API request using the Authorization header with the Bearer scheme. An API key is also required and must be passed in the X-Api-Key header.

Get an Access Token

Before accessing any secured endpoint in the Architect APIs, your application must first obtain an access token from ATPCO's OAuth 2.0 token endpoint.

This step involves making an HTTP POST request using the Client Credentials grant type—ideal for machine-to-machine communication where a trusted backend system is accessing the API.

Prerequisites

Ensure you have been issued the following credentials from ATPCO:

📝 To request credentials, create a ServiceNow ticket on the ATPCO Portal.

Your client credentials are configured with the needed scope to access the APIs. The appropriate scopes are assigned during onboarding—you do not need to request or manage them separately.

Token Request – Endpoint and Format

HTTP Method: POST

Required Header

Required Body Parameters

📝 Parameters must be sent as a form URL-encoded body, not as JSON.

Sample curl Request

curl --location '<token-endpoint-url>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<your-client-id>' \
--data-urlencode 'client_secret=<your-client-secret>' \
--data-urlencode 'scope=<your-scope>' \
--data-urlencode 'grant_type=client_credentials'

📝 The token endpoint URL and scope are provided during onboarding. Refer to the API specifications for the available authorizations:

• Blueprint API – Available Authorizations
• Substime API – Available Authorizations

📝 You can use --data instead of --data-urlencode if you manually encode any special characters (like +, @, :) in the values.

Authentication Flow (Client Credentials Grant)

The authentication process begins when your application (the client) sends a POST request to the /token endpoint of the authorization server, including the client_id, client_secret, requested scope, and grant_type=client_credentials. The authorization server verifies these credentials, and if the request is valid, issues an access token.

The access token represents your application's identity and granted permissions. You then include this access token in the Authorization header when invoking the Architect APIs. The issued token is typically valid for 1 hour (3600 seconds), after which your application must request a new token using the same process.

Example Response

A successful token response follows the format defined in RFC 6749 Section 4.1.4 – Access Token Response:

Error Handling:

If you receive a 401 Unauthorized response, verify your Client ID, Secret, and Scope.

Using the Access Token to Call the API

Once you have successfully retrieved the access_token from the OAuth 2.0 token endpoint, you can use it to authenticate your requests to the Architect APIs. The access token must be included in the Authorization header, and the API key must be included in the X-Api-Key header of each request.

Example: Get all blueprints

curl '<base-url>/architect/blueprint/blueprints' \
--header 'Authorization: <your-access-token>' \
--header 'X-Api-Key: <your-api-key>' \
--header 'Accept: application/json'

Example: Get subscription times

curl '<base-url>/architect/substime' \
--header 'Authorization: <your-access-token>' \
--header 'X-Api-Key: <your-api-key>' \
--header 'Accept: application/json'

📝 For the full list of available endpoints and base URLs, refer to the API specifications:

• Blueprint API
• Substime API