Securing the Configuration API

The Configuration API is secured by Microsoft Entra ID and users are required to create an access (bearer) token for authorisation. The token is used in the authorisation headers on any subsequent calls that require authorisation.

Generate an access (bearer) token to use with the Configuration API

The basic flow of creating and using the access token is as follows:

Send a request with valid details to the token endpoint
Receive an access token in the response
Each call you make will automatically include the token in the call's authorisation header.

Information required to get an access token

Using the Management Portal

The Management Portal handles all required actions to acquire a Bearer token.

Using a REST API Client

The access token request endpoint

POST https://login.microsoftonline.com/{{PermissionsTenantId}}/oauth2/v2.0/token

Access token request headers

Header	Value
Content-Type	application/x-www-form-urlencoded

Access token request URL parameters

Parameter	Type	Value
PermissionsTenantId	string	The directory ID of the tenant associated with the instance of Cenda.

The tenant specified above is used to give applications permissions to access the system and will need to be created as mentioned previously.

Access token request body parameters

All parameters in the table below are required.

Parameter	Type	Value
grant_type	string	Must be `client_credentials`.
client_id	guid	The ID of the client application registered in the permissions tenant.
client_secret	string	The corresponding client secret for the client specified above.
scope	string	The scope of permissions that the token has access to. This uses the `GatewayClientId`.

Access token request body

POST https://login.microsoftonline.com/{{PermissionsTenantId}}/oauth2/v2.0/token
Content-type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={{ApiClientId}}
&client_secret={{ApiClientSecret}}
&scope={{GatewayClientId}}/.default

Access token request response

A successful call will return a 200 OK status code and the access_token value in the returned JSON body.

{
  "token_type": "string",
  "expires_in": int,
  "ext_expires_in": int,
  "access_token": "string"
}

An unsuccessful call will return a 400 Bad Request status code and an error message which should highlight the parameter(s) that needs checking.

{
  "error": "string",
  "error_description": "string",
  "error_codes": [
    int
  ],
  "timestamp": "string",
  "trace_id": "string",
  "correlation_id": "string",
  "error_uri": "string"
}

Sample success response (200)

{
  "token_type": "Bearer",
  "expires_in": 600,
  "ext_expires_in": 600,
  "access_token": "eyJ..."
}

Sample unsuccessful response (400)

If any values are invalid or missing, an error message will be returned and should highlight the area to check. In this example, the client secret provided was invalid, and the error property states the type of error, and the error_description provides more information.

{
  "error": "invalid_client",
  "error_description": "AADSTS7000215: Invalid client secret provided. Ensure the secret being sent in the request is the client secret value, not the client secret ID, for a secret added to app '0f70ea2d-6371-4acc-9035-31a22887a8a4'. Trace ID: 60232ebf-feda-4e57-976b-7a74f11a7e00 Correlation ID: 08c3117b-8e36-4114-9bf0-053feb27299c Timestamp: 2023-11-13 21:15:44Z",
  "error_codes": [
    7000215
  ],
  "timestamp": "2023-11-13 21:15:44Z",
  "trace_id": "60232ebf-feda-4e57-976b-7a74f11a7e00",
  "correlation_id": "08c3117b-8e36-4114-9bf0-053feb27299c",
  "error_uri": "https://login.microsoftonline.com/error?code=7000215"
}

All calls for onboarding management assume that you have retrieved an access token (referenced as access_token) - without a valid access token, you will be unable to access the API and will receive an unauthorised (401) response when calling the endpoints. You will also need an access token to test out the swagger documentation and postman collection.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"