Service Authentication

When sending usage data to m3ter or accessing the API directly, you should always use Service Authentication. To control access to m3ter by Service Users, we implement the OAuth 2.0 Client Credentials Grant authentication flow. In accordance with this grant type, to use Service Authentication you must first obtain a Bearer Token to use for access when making API calls to the m3ter platform. You can use Basic Authentication to obtain a Bearer Token. For Basic Authentication, you will first need an api key and api secret.

OAuth 2.0 Client Credentials Grant? If you are not already familiar with this type of client credentials authorization flow, we strongly recommend you consult the OAuth 2.0 Clients Credentials documentation first.

This topic explains how to generate access keys and obtain Bearer Tokens for your Service Users.

Tip: Creating and Managing Service Users? For more details, see Creating and Configuring Service Users.

Generating an API Key and Secret for a Service User

You can generate an Access Key id and Api Secret for a Service User from within the m3ter Console:

• When you first create a Service User, you can choose to generate access keys - see Creating a Service User.
• Alternatively, you can open the details page for a Service User and generate access keys. You will likely want to rotate access keys at regular intervals as good security practice by making existing keys inactive and generating new ones.

To generate access keys for Service Users:

1. On the Settings>Access>Service Users tab, select the NAME text of the Service User. The details page for the Service User opens. Any access keys generated for the Service User are listed in the Access Keys panel.
2. Select Generate Access Key. A Generate Access Key popup appears, which shows:

• Organization ID
• Access Key ID
• API Secret

You can copy each of these string values directly to your clipboard.

Important! When you generate an access key for a Service User, you need to keep a record of the Api Secret before you close the popup, because this will only be shown once.

3. On the Generate Access Key popup, select Close. You are returned to the details page where the access key is listed as ACTIVE on the Access Keys panel.

You can now use the Access Key id and Api Secret to authenticate the Service User to m3ter using the Basic Authentication method and obtain a Bearer Token for making subsequent API calls.

4. If you want to generate additional access keys, you can repeat steps 2 to 3. If you generate additional keys, you should take care to mark the old ones as Inactive - those for which you cannot remember or find the Api Secret or those no longer required due to rotation.

Tip: Rotating Access Keys? Note that you can only create up to two Access Keys at a time - if you want to maintain continual rotation of your Service User Access Keys, after creating two you must first inactivate and remove one to create a new one.

Obtaining a Bearer Token Using Basic Auth

When you have generated access keys for a Service User as explained in the previous section, you can use them with Basic Authentication to obtain a Bearer Token. This section gives some examples of how to obtain a Bearer Token using Basic Auth:

• Example Using Postman
• Example Using cmd Line
• Example Using Python Script

Tip: API Reference Docs? When obtaining a Bearer Token for a Service User, please see the Auth section of our API Reference Docs.

Example Using Postman

This example uses Postman to obtain a Service User Bearer Token using Basic Authentication.

To obtain a Bearer Token using access keys in Postman:

1. In your Postman workspace, select to make a POST call and enter this URL as the endpoint:

https://api.m3ter.com/oauth/token

2. On the Authorization tab, for Type select Basic Auth and copy and paste your Service User Access Key id for Username and Api Secret for Password:

3. Select the Body tab and enter this JSON:

4. Click Send. Your Bearer Token is generated and loaded into the Body tab of the Response panel in Postman as the "access_token" value:

Warning: The Bearer Token is valid for 18000 seconds or 5 hours, after which time has elapsed, you will have to obtain a new one.

You can now use your Bearer Token when making API calls to m3ter.

Important! You must assign Administrator Permissions to a Service User to allow the user to make API calls to the Service. See Adding Permissions to Service Users.

Example Using cmd Line

This example uses the cmd line to obtain a Service User Bearer Token using Basic Authentication.

To obtain a Bearer Token using access keys from the cmd line:

1. Encode the Access  key id and Api Secret as base64 and use the value as in Step 2:
2. Encode the Access  key id and Api Secret as base64 and use the value as {{basicAuth}} in Step 2:

base64(${Access key id}:{Api Secret})

2. Submit the following:

curl --location --request POST 'https://api.m3ter.com/oauth/token' \
--header 'Authorization: Basic {{basicAuth}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type": "client_credentials"
}'

The response is:

{
    "token_type": "Bearer",
    "access_token": "xx",
    "expires_in": 18000
}

You can now use the returned access_token value as a Bearer Token in API calls to m3ter.

3. Alternatively, you can skip the base64 encoding at Step 1, and simply use:

curl --location --request POST 'https://api.m3ter.com/oauth/token' \
-u {Access key id}:{Api Secret} \
--header 'Content-Type: application/json' \
--data-raw '{
 "grant_type": "client_credentials"
}'

In other words, use the -u option and specify the Access key id and Api Secret separated by colon.

Example using Python Script

For an example of how to obtain a Bearer Token using a Python script, please see the Authentication and Authorization section in the introduction to our API Reference documentation.