API Authentication
The Product Catalog Exchange 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. This approach enables secure, authenticated access to the APIs while protecting sensitive backend identity infrastructure.
Get an Access Token
Before accessing any secured endpoint in the Product Catalog APIs, your application must first obtain an access token from the OAuth 2.0 token endpoint hosted by ATPCO’s Azure B2C Identity Provider.
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:
| Credential | Description |
|---|---|
| Client ID | A unique identifier of your application |
| Client Secret | A private key that must be kept secure |
| Scope | Defines which API your application is requesting access to |
Token Request – Endpoint and Format
HTTP Method: POST
URL: https://<auth server>/<flow>/oauth2/v2.0/token
Required Header
| Header | Value |
|---|---|
| Content-Type | application/x-www-form-urlencoded |
Required Body Parameters
| Parameter | Value |
|---|---|
| client_id | Your application’s registered client ID |
| client_secret | Your application’s client secret |
| grant_type | Must be client_credentials to use this server-to-server flow |
| scope | The scope you're requesting (must match what your app is registered for) |
⚠️ Parameters must be sent as a form URL-encoded body, not as JSON.
Sample curl Request
Here’s an example curl command to request a token:
⚠️ 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 (Azure B2C), 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 a JSON Web Token (JWT) as the 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 Product Catalog APIs, using the format: Authorization: Bearer <access_token>. 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 looks like this:
| Field | Description |
|---|---|
| access_token | The token you must use in the Authorization: Bearer header for API requests |
| token_type | Always Bearer for OAuth 2.0 |
| not_before | Timestamp (epoch seconds) before which the token is invalid |
| expires_in | Duration (in seconds) for which the token is valid (typically 3600s = 1 hour) |
| expires_on | Exact timestamp (epoch seconds) when the token expires |
| resource | Internal identifier for the API resource (for system purposes) |
Error Handling:
If you receive a 401 Unauthorized response, verify your Client ID, Secret, and Scope.
Using 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 Product Catalog APIs. The access token must be included in the Authorization header of each API request, following the Bearer Token scheme as shown in the following example.