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 service. You can use Basic Authentication 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.
To create a Service User and generate access keys:
1. Log in to the m3ter Console and under Settings>Users select the Service Users tab. Existing Service Users are listed.
2. If none are listed and you need to create one, select Create Service User.
3. On the Create page, enter a Name and select Create Service User. Your new Service User is added to the list on the Service Users tab.
4. Select the NAME text of the new Service User. The Service User Overview page opens. This page is where you add Permissions and generate access keys. Note that you must add Permissions to enable users to perform any actions on the service, such as Administrator Permission to be able to submit API calls - see Creating and Configuring Service Users.
5. On the Access Keys panel, select Generate Access Key. An Access Key ID and Api Secret are generated for the Service User and are shown on a Generate Access Key popup window, along with your Organization ID. Note that you can Copy any 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 window, because this will only be shown once.
6. Click to Close the Generate Access Key popup window. You are returned to the Service User Overview page where the new Access Key id is shown.
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.
7. If you want to generate additional access keys, you can repeat steps 4 to 6. 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.
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 the 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 {{basicAuth}} in Step 2:
base64(${Access key id}:{Api Secret})
2. Submit the following:
1curl --location --request POST 'https://api.m3ter.com/oauth/token' \2--header 'Authorization: Basic {{basicAuth}}' \3--header 'Content-Type: application/json' \4--data-raw '{5"grant_type": "client_credentials"6}'
The response is:
1{2"token_type": "Bearer",3"access_token": "xx",4"expires_in": 180005}
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:
1curl --location --request POST 'https://api.m3ter.com/oauth/token' \2-u {Access key id}:{Api Secret} \3--header 'Content-Type: application/json' \4--data-raw '{5"grant_type": "client_credentials"6}'
In other words, use the -u option and specify the Access key id and Api Secret separated by colon.
Next: m3ter APIs