CAS Service API uses OpenID Connect as authentication protocol and OAuth 2.0 as authorization protocol. The client application should obtain a token using the Client Credentials Grant.

With Client Credentials Grant (defined in RFC 6749, section 4.4) a Non Interactive Client (a CLI, a daemon, or a Service running on your backend), can directly ask identity provider for an access_token, by using its Client Credentials (Client Id and Client Secret) to authenticate. In this case the token represents the Non Interactive Client itself, instead of an end user. Following are the steps related to this flow:

1. The application authenticates with the CAS authorization server using its Client Id and Client Secret.
2. The CAS authorization server validates and returns an Access Token.
3. The application caches the access token and uses it as Bearer token in the authorization header when calling API functions on the CAS API.
4. The application stops using the access token once it has expired. The token response indicates when this token will expire, see expires_in (defined in seconds). Alternatively, any API function will return a 401 Unauthorized response when using an expired token. A new access token can be requested using the same process.

Client Id / Client Secret

Customs4trade Customer Success team will provide the Client Id and Client Secret, which you will need to get an OAuth 2.0 authorization token.

If you have multiple source systems that communicate with one of the CAS Service APIs, you will receive different sets of Client Ids and Client Secrets. The reference of your source system will be part of the Bearer token.

To view the details of a token returned using a certain Client Id and Client Secret you can just decode the JWT token or make a call to v1/authorizationStatus on the API endpoint. This method will echo following info:

• The Client ID which corresponds to the assigned tenant ID.
• The assigned source system reference.
• The assigned scopes.

Usage

After receiving the token from the OAuthToken API you will have to store this token as it needs to be provided for each call that is made to the APIs. The token validity duration is also returned in the callback message. We strongly advise to cache this token so you don't need to call the Authorization API with every request. You can then refresh the token within the alloted time period or wait for a 401 (Unauthorized) response to do so.

The token validity duration could be changed in the future for security reasons, so please use the value given in the 'expires_in' field and don't hard code the time period.

Authentication request

To authenticate, you need to make a request in "application/x-www-form-urlencoded" format to the relevant token endpoint to retrieve a bearer token.

https://login.customs4trade.com/oauth2/v2.0/token (production) or https://login-acc.customs4trade.com/oauth2/v2.0/token (acceptance)

An example of the body of the request is shown below. Replace the variables by the appropriate values for your tenant in CAS.

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&scope=https%3A%2F%2Fc4t{env}b2c.onmicrosoft.com%2F{client_id}%2F.default

A successful request, will result in a JSON response containing the bearer token which can be used in the Authorization header as "Bearer {token}".

{
    "token_type": "Bearer",
    "expires_in": 3599,
    "ext_expires_in": 3599,
    "access_token": "{token}"
}

Take care to use the correct scope for respectively the acceptance or production environment

The /.default suffix in the scope URI requests all scopes that have been configured for your application. This is required when using the Client Credentials Grant — you cannot request individual scopes. The CAS identity provider returns a token containing all scopes assigned to your client application.

Scopes

Scopes control which API operations your token is authorized to perform. Each scope follows the format {action}:{resource}. The following scopes are available:

Verifying your token

To verify that your token is valid and inspect the claims it contains, you can call the Authorization Status endpoint:

GET https://api-<env>.customs4trade.com/v1/authorizationStatus
Authorization: Bearer {token}

This returns:

{
    "sourceSysRef": "your-source-system-reference",
    "tenantIds": "tenant-id-1 tenant-id-2",
    "scopes": "create:messages read:declarations create:subscriptions read:subscriptions delete:subscriptions"
}

Tenant identification

Your token contains a tenant ID that determines which tenant's data you can access. All API calls automatically target the tenant associated with your token.