Accessing the UsageCloud APIs
This page describes how an external application communicates with the Usage Engine APIs using Client credentials. You need an authorization token to access the Usage Engine API. See the following example:
Example - Authorization token
{"access_token":{{Encoded token}},
"scope":"create:meter_types create:meters",
"expires_in":3600,
"token_type":"Bearer"}By design, the Client credentials flows do not have a refresh flow, so a new access token needs to be requested every time the token expires. The tokens are valid for one hour. As part of the authorization token, you will receive the lifetime (expires_in) of the token in seconds.
Obtaining and using access tokens: step-by-step
The external application uses the credentials (Client ID and Client Secret) to authenticate with the Usage Engine Identity Provider (IdP) and requests a token to access the API. To create token you also need to provide audience and grant type. See Creating an application access.
Note!
Only Administrators can create Application accesses.
The IdP verifies the credentials and generates a temporary token, referred to as
<access token>in the following steps.The external application sends the
<access token>to access a resource in an API, for example, the Online collection API.The API checks with the IdP if the
<access token>is valid and if the application has permission to access the requested resource/functionality.If the
<access token>is valid, the permission is granted.The API responds to the requests with the results of the operation.
Example - Getting an OAuth 2 Token Using curl
This works in bash and zsh. To avoid exposing the credentials we are storing them in variables. For information about how to define variables in any other environment, see the respective documentation. The Client Secret is sensitive information and it is important not to expose it unnecessarily. The audience is the API address you are going to send requests to.
client_id={{your client ID}}
client_secret={{your client secret}}
audience={{your api environment}}
curl --location --request POST 'https://api.digitalroute.io/authentication/v1/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data client_id=${client_id} \
--data client_secret=${client_secret} \
--data grant_type='client_credentials' \
--data audience=${audience}
Parameter | Description |
|---|---|
access_token | The access token string that is issued by the authorization server. |
scope | Scopes defined for the token |
expires_in | Validity of the token in seconds |
token_type | The type of token this is, just the string “Bearer”. |
This section has the following subsections: