API docs by Redocly

Usage Engine Cloud Edition API

Download OpenAPI specification:Download

Usage Engine offers several different APIs for performing various tasks using external systems.

HTTP error response codes

The following error response codes are used in the system:

Error code Explanation
400 Bad request
401 Unauthorized
404 Not found
405 Method not allowed
409 Conflict
429 Too many requests
500 An unexpected internal error occurred even though the request was valid
503 Service unavailable

Authentication

With the authentication API you can create tokens for OAuth authentication. The API supports OAuth 2.0.

Create access token

Use POST /oauth/token to create a bearer access token enabling an OAuth client to authenticate itself in the Usage Engine REST API. You have to create an Application Access in Usage Engine to retrieve the client ID and client secret, see Application Access for detailed instructions.

Request Body schema: application/json

Credentials used for authenticating the client to the authorization server.

audience
required
string

The intended recipients which should accept and process the token. Use the base URL for the environment you are accessing.

client_id
required
string

The client ID generated when creating the Application Access in Usage Engine CE.

client_secret
required
string

The client secret generated when creating the Application Access in Usage Engine CE.

grant_type
required
string

The OAuth grant type that will be used to generate the token. The value of this parameter must be client_credentials.

Responses

Request samples

Content type
application/json
{
  • "audience": "https://api.digitalroute.io/",
  • "client_id": "u4grtTy18E2DYANsv0G174aSxR3EeOiA",
  • "client_secret": "U6qN9NTgis3MLeleRXtLgIxtRE-qhpZcPJ_5eoNtNQYcodiY9q0Abs3afgpbX3M6",
  • "grant_type": "client_credentials"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImZUYU5saGpnclFERE0xYkdVZG1WeiJ9.eyJhY2NvdW50SWQiOiJhZDZmZWM5NS1lMDYzLTQ5MmItOTJjYy01MmJiNjJjMGU3NTAiLCJpc3MiOiJodHRwczovL2F1dGguZGlnaXRhbHJvdXRlLmlvLyIsInN1YiI6IjhtMUhUMHA2SkdMOVJjbzhWNEZjWGZ2Y2dHejcwcms4QGNsaWVudHMiLCJhdWQiOiJodHRwczovL2FwaS5kaWdpdGFscm91dGUuaW8vIiwiaWF0IjoxNzEyMTQ0OTQzLCJleHAiOjE3MTIxNDg1NDMsInNjb3BlIjoiY3JlYXRlOm1ldGVyX3R5cGVzIGNyZWF0ZTptZXRlcnMgZGVsZXRlOm1ldGVyX3R5cGVzIGRlbGV0ZTptZXRlcnMgcmVhZDptZXRlcl90eXBlcyByZWFkOm1ldGVycyB1cGRhdGU6bWV0ZXJfdHlwZXMiLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMiLCJhenAiOiI4bTFIVDBwNkpHTDlSY284VjRGY1hmdmNnR3o3MHJrOCJ9.VS8Ti1zTK4b8qGRKXJg8b0-aMpNpTTL1_nwsPbCeM7CFlUYu45ZUQGWvUqC6XGK-Xl3j9k5Tkth8TtFbbXNEW4mEV0e1qQbDu_ZlvH-bH2nCNJhk-7mFriGYfTF0U-erqNiMsk4Tbrmm2Voy9CJ4_WyVrCjTLBqRBKb_bU4KHFJtgadlqwaTVNZUiI-sIV3Y2V_gid_4qPTO1Vr01ybID_F8uNII9goDqPJBRh6hmcKHqt65U5n2xzbmBcNqRPoXqxh1g9OaYEPDjojp2lHttqs2EkGG9KxzTFqhdX4lcrjfHGgzNk7LD7S7mGJTO0V-n57geptxM7gFGr-hAQ4Ikg",
  • "expires_in": 3600,
  • "scope": "create:meter_types create:meters delete:meter_types delete:meters read:meter_types read:meters update:meter_types",
  • "token_type": "Bearer"
}

Meter type

The meter type is a representation of the product or service you want to offer with a usage based billing model.

List meter types

Use GET /meter-types to retrieve a list of all meter types configured within your account.

Authorizations:
OAuth 2.0 Bearer Token
query Parameters
limit
string

Defines the number of meter types to be returned. A maximum of 100 items can be returned.

skip
string

Defines an offset for the meter types to be returned. If you set skip to 10, the first 10 meter types will be skipped in the returned list.

sortOrder
string

Determines the sort order of the returned list; ASC for ascending or DESC for descending.

sortBy
string

Determines the field in the meter type by which the returned list will be sorted.

name
string

Defines the name for which meter type should be returned. You may provide full or partial name.

header Parameters
X-Account-Id
string
X-Application-Id
string

Responses

Response samples

Content type
application/json
{
  • "meterTypes": [
    ]
}

Create meter type

Use POST /meter-types to create a new meter type for your account.

Authorizations:
OAuth 2.0 Bearer Token
header Parameters
X-Account-Id
string
X-Application-Id
string
Request Body schema: application/json
activeFrom
string

Determines from which date and time the meter type will be active, with the time based on UTC. The date and time cannot be in the past, and if this parameter is left undefined, the current date and time will be picked.

activeTo
string

Determines to which date and time the meter type will be active, with the time based on UTC. The date and time cannot be in the past, and if this parameter is left undefined, it will be active indefinitely.

required
object

Choose the aggregation type for aggregating data within a defined interval.

  • Sum: Summarize all values.
  • Increment: Count the number of occurrences.
  • Max: Highest value received.
  • Min: Lowest value received.

The aggregation type cannot be updated.

category
string <= 50 characters

Specify the category to which the meter type should be assigned. By using the category when configuring the Meter processor, meter types can be added, edited, or deleted without necessarily affecting the Meter processor configuration. If no category is specified, the meter type will be assigned to the DEFAULT category.

description
string <= 200 characters

You can add a more detailed description for the meter type with this parameter.

externalRef
string <= 100 characters

If the meter type is registered as a product in an external system, you can add the external ID to reference it.

name
required
string <= 80 characters ^[\w\s().-]+$

Name of the meter type. Only alphanumeric characters, spaces, and the following special characters are supported - _ . ( )

required
object

Determines how often the usage counting data should be reset and sent to downstream systems defined in crontab format.

timezone
required
string

The canonical timezone that should be applied for reset time. See IANA time zones for the complete available list.

unit
required
string <= 50 characters

State the unit which the meters should be measuring, such as MB, minutes, etc.

Responses

Request samples

Content type
application/json
{
  • "activeFrom": "2023-07-26T09:00:15.690+00:00",
  • "activeTo": "2024-11-22T00:00:00.000+00:00",
  • "aggregation": {
    },
  • "category": "API Counts",
  • "description": "Meter definition to count the number of API requests per customer",
  • "externalRef": "878752b4-4ddf",
  • "name": "Usage based API counter",
  • "resetSchedule": {
    },
  • "timezone": "Etc/UTC",
  • "unit": "requests"
}

Response samples

Content type
application/json
{
  • "accountId": "4d6548c8-1793-498f-9306-9ec101cb9bf8",
  • "activeFrom": "2023-07-26T09:00:15.690+00:00",
  • "activeTo": "2024-11-22T00:00:00.000+00:00",
  • "aggregation": {
    },
  • "category": "API Counts",
  • "createdAt": "2023-07-26T09:00:15.690+00:00",
  • "description": "Meter definition to count the number of API requests per customer",
  • "externalRef": "878752b4-4ddf",
  • "id": "645ed240-02b5-400c-9a3c-21857e8f2ac4",
  • "name": "Usage based API counter",
  • "numberOfMeters": 0,
  • "resetSchedule": {
    },
  • "timezone": "Etc/UTC",
  • "unit": "requests",
  • "updatedAt": "2023-07-26T09:00:15.690+00:00"
}

Delete meter type

Use DELETE /meter-types/{id} to delete a specified meter type. It is not allowed to delete meter type with associated meters. You must delete associated meters first to delete meter type.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of meter type.

header Parameters
X-Account-Id
string
X-Application-Id
string

Responses

Response samples

Content type
application/json
{
  • "deletedCount": 1
}

Get meter type

Use GET /meter-types/{id} to retrieve information about a specified meter type.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of meter type.

header Parameters
X-Account-Id
string
X-Application-Id
string

Responses

Response samples

Content type
application/json
{
  • "accountId": "4d6548c8-1793-498f-9306-9ec101cb9bf8",
  • "activeFrom": "2023-07-26T09:00:15.690+00:00",
  • "activeTo": "2024-11-22T00:00:00.000+00:00",
  • "aggregation": {
    },
  • "category": "API Counts",
  • "createdAt": "2023-07-26T09:00:15.690+00:00",
  • "description": "Meter definition to count the number of API requests per customer",
  • "externalRef": "878752b4-4ddf",
  • "id": "645ed240-02b5-400c-9a3c-21857e8f2ac4",
  • "name": "Usage based API counter",
  • "numberOfMeters": 0,
  • "resetSchedule": {
    },
  • "timezone": "Etc/UTC",
  • "unit": "requests",
  • "updatedAt": "2023-07-26T09:00:15.690+00:00"
}

Update meter type

Use PATCH /meter-types/{id} to update a specified meter type.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of meter type.

header Parameters
X-Account-Id
string
X-Application-Id
string
Request Body schema: application/json
string or null

The new active from date you want the meter type to use.

string or null

The new active to date you want the meter type to use.

string or null <= 50 characters

The new category you want the meter type to use. You may need to revise the configuration in the Meter processor following the category update.

description
string <= 200 characters

The updated description you want the meter type to have.

string or null <= 100 characters

The new external ID you want to associate with the meter type.

name
string <= 80 characters ^[\w\s().-]+$

The new name you want the meter type to have. Only alphanumeric characters, spaces, and the following special characters are supported - _ . ( ).

object

The new reset schedule you want the meter type to use. The new reset schedule takes effect after the current period has ended and meters have been reset.

timezone
string

The new canonical timezone you want the meter type to use. See IANA time zones for the complete available list.

unit
string <= 50 characters

State the unit which the meters should be measuring, such as MB, minutes, etc.

Responses

Request samples

Content type
application/json
{
  • "activeFrom": "2023-07-26T09:00:15.690+00:00",
  • "activeTo": "2024-11-22T00:00:00.000+00:00",
  • "category": "API Counts",
  • "description": "Meter definition to count the number of API requests per customer",
  • "externalRef": "878752b4-4ddf",
  • "name": "Usage based API counter",
  • "resetSchedule": {
    },
  • "timezone": "Etc/UTC",
  • "unit": "requests"
}

Response samples

Content type
application/json
{
  • "accountId": "4d6548c8-1793-498f-9306-9ec101cb9bf8",
  • "activeFrom": "2023-07-26T09:00:15.690+00:00",
  • "activeTo": "2024-11-22T00:00:00.000+00:00",
  • "aggregation": {
    },
  • "category": "API Counts",
  • "createdAt": "2023-07-26T09:00:15.690+00:00",
  • "description": "Meter definition to count the number of API requests per customer",
  • "externalRef": "878752b4-4ddf",
  • "id": "645ed240-02b5-400c-9a3c-21857e8f2ac4",
  • "name": "Usage based API counter",
  • "numberOfMeters": 0,
  • "resetSchedule": {
    },
  • "timezone": "Etc/UTC",
  • "unit": "requests",
  • "updatedAt": "2023-07-26T09:00:15.690+00:00"
}

Meter

A meter is a customer-specific counter. The meter defines which meter types the customer’s usage should be counted for. Unique meters should be created for all customers.

List meters

Use GET /meters to retrieve a list of available meters configured in the system.

Authorizations:
OAuth 2.0 Bearer Token
query Parameters
limit
string

Defines the number of meters to be returned. A maximum of 100 items can be returned.

skip
string

Defines an offset for the meters to be returned. If you set skip to 10, the first 10 meters will be skipped in the returned list.

meterKey
string

Defines the meter key for which meters should be returned.

meterTypeId
string

Defines the meter type ID for which meters should be returned.

userId
string

Defines the user ID for which meters should be returned.

header Parameters
X-Account-Id
string
X-Application-Id
string

Responses

Response samples

Content type
application/json
{
  • "meters": [
    ]
}

Create meter

Use POST /meters to create a new meter.

Authorizations:
OAuth 2.0 Bearer Token
header Parameters
X-Account-Id
string
X-Application-Id
string
Request Body schema: application/json
One of
meterKey
required
string <= 36 characters

The meter key for the Meter processor counting the usage for the meter.

meterTypeId
required
string <= 36 characters

The unique ID of the meter type that the meter should count usage for.

userId
required
string <= 320 characters

Unique ID of the user the meter belongs to, for example an email address, user name or MSISDN number.

Responses

Request samples

Content type
application/json
Example
{
  • "meterKey": "a1f8797b-c827-4483-b6cf-6d3d3baa18a7",
  • "meterTypeId": "645ed240-02b5-400c-9a3c-21857e8f2ac4",
  • "userId": "user0@example.com"
}

Response samples

Content type
application/json
{
  • "carryFirst": {
    },
  • "carryLast": {
    },
  • "createdAt": "2023-07-01T00:00:00.000Z",
  • "deleteOnReset": false,
  • "groups": [
    ],
  • "id": "8a76066d-ff29-417c-a18e-abde22e44310",
  • "meterKey": "a1f8797b-c827-4483-b6cf-6d3d3baa18a7",
  • "meterMetaData": {
    },
  • "meterTypeId": "645ed240-02b5-400c-9a3c-21857e8f2ac4",
  • "meterTypeName": "Usage based API counter",
  • "periodEnd": "2023-08-01T00:00:00.000Z",
  • "periodStart": "2023-07-01T00:00:00.000Z",
  • "timezone": "Etc/UTC",
  • "unit": "requests",
  • "updatedAt": "2023-07-05T22:01:04.431Z",
  • "userId": "user0@example.com",
  • "value": 25
}

Delete meter

Use DELETE /meters/{id} to delete a specified meter.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of meter.

header Parameters
X-Account-Id
string
X-Application-Id
string

Responses

Response samples

Content type
application/json
{
  • "deletedCount": 1
}

Get meter

Use GET /meters/{id} to retrieve information about a specified meter.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of meter.

header Parameters
X-Account-Id
string
X-Application-Id
string

Responses

Response samples

Content type
application/json
{
  • "carryFirst": {
    },
  • "carryLast": {
    },
  • "createdAt": "2023-07-01T00:00:00.000Z",
  • "deleteOnReset": false,
  • "groups": [
    ],
  • "id": "8a76066d-ff29-417c-a18e-abde22e44310",
  • "meterKey": "a1f8797b-c827-4483-b6cf-6d3d3baa18a7",
  • "meterMetaData": {
    },
  • "meterTypeId": "645ed240-02b5-400c-9a3c-21857e8f2ac4",
  • "meterTypeName": "Usage based API counter",
  • "periodEnd": "2023-08-01T00:00:00.000Z",
  • "periodStart": "2023-07-01T00:00:00.000Z",
  • "timezone": "Etc/UTC",
  • "unit": "requests",
  • "updatedAt": "2023-07-05T22:01:04.431Z",
  • "userId": "user0@example.com",
  • "value": 25
}

Update meter

Use PATCH /meters/{id} to update a specified meter.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of meter.

header Parameters
X-Account-Id
string
X-Application-Id
string
Request Body schema: application/json
deleteOnReset
boolean

Determine whether the meter should be deleted after the next reset.

Responses

Request samples

Content type
application/json
{
  • "deleteOnReset": true
}

Response samples

Content type
application/json
{
  • "carryFirst": {
    },
  • "carryLast": {
    },
  • "createdAt": "2023-07-01T00:00:00.000Z",
  • "deleteOnReset": false,
  • "groups": [
    ],
  • "id": "8a76066d-ff29-417c-a18e-abde22e44310",
  • "meterKey": "a1f8797b-c827-4483-b6cf-6d3d3baa18a7",
  • "meterMetaData": {
    },
  • "meterTypeId": "645ed240-02b5-400c-9a3c-21857e8f2ac4",
  • "meterTypeName": "Usage based API counter",
  • "periodEnd": "2023-08-01T00:00:00.000Z",
  • "periodStart": "2023-07-01T00:00:00.000Z",
  • "timezone": "Etc/UTC",
  • "unit": "requests",
  • "updatedAt": "2023-07-05T22:01:04.431Z",
  • "userId": "user0@example.com",
  • "value": 25
}