Accessing the Usage Engine CE APIs

This page describes the high-level steps of 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 of an authorization token:

Example:

{"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.

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 Configuring Application Access for information on how to create the application access.

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, Usage Metering 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. Read more at Getting started with APIs using Curl

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

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”.

See examples in Getting started with APIs calls using Postman and Getting started with APIs using Curl for more information about how to use the generated access token to access the APIs.