Authentication and Authorization

Our APIs use an industry-standard authorization protocol known as the OAuth 2.0 specification. OAuth2 supports several grant types, each designed for a specific use case. m3ter uses the following two grant types:

• Authorization Code: Used for human login access via the m3ter Console.
• Client Credentials: Used for machine-to-machine communication and API access.

Complete the following flow for API access:

1. Create a Service User and add Permissions

   Log in to the m3ter Console, go to Settings, Access then Service Users tab, and create a Service User. To enable API calls, grant the user Administrator permissions.

2. Generate Access Keys

   In the Console, open the Overview page for the Service User by clicking on the name. Generate an Access Key id and Api Secret. Make sure you copy the Api Secret because it is only visible at the time of creation. See Service Authentication for detailed instructions and an example.

3. Obtain a Bearer Token using Basic Auth

   We implement the OAuth 2.0 Client Credentials Grant authentication flow for Service User Authentication. Submit a request to the m3ter OAuth Client Credentials authentication flow, using your concatenated Access Key id and Api Secret to obtain a Bearer Token for your Service User. See examples below.

4. Bearer Token Usage

   Use the HTTP ‘Authorization’ header with the bearer token to authorise all subsequent API requests.

The Bearer Token is valid for 18,000 seconds or 5 hours. When the token has expired, you must obtain a new one.

Below are two examples for obtaining a Bearer Token using Basic Auth: the first in cURL and the second as a Python script.

cURL Example

1. Open your terminal or command prompt.
2. Use the following cURL command to obtain a Bearer Token:

curl -X POST https://api.m3ter.com/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u your_access_key_id:your_api_secret \
  -d 'grant_type=client_credentials'

Replace your_access_key_id and your_api_secret with your actual Access Key id and Api Secret.

3. Run the command, and if successful, it will return a JSON response containing the Bearer Token. The response will look like this:

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

You can then use the Bearer Token (the value of "access_token") for subsequent API calls to m3ter.

Python Example

1. Install the requests library if you haven’t already:

pip install requests

2. Use the following Python script to obtain a Bearer Token:

import requests
import base64
# Replace these with your Access Key id and Api Secret
access_key_id = 'your_access_key_id'
api_secret = 'your_api_secret'
# Encode the Access Key id and Api Secret in base64 format
credentials = base64.b64encode(f'{access_key_id}:{api_secret}'.encode('utf-8')).decode('utf-8')
# Set the m3ter token endpoint URL
token_url = 'https://api.m3ter.com/oauth/token'
# Set the headers for the request
headers = {
    'Authorization': f'Basic {credentials}',
    'Content-Type': 'application/x-www-form-urlencoded'
}
# Set the payload for the request
payload = {
    'grant_type': 'client_credentials'
}
# Send the request to obtain the Bearer Token
response = requests.post(token_url, headers=headers, data=payload)
# Check if the request was successful
if response.status_code == 200:
    # Extract the Bearer Token from the response
    bearer_token = response.json()['access_token']
    print(f'Bearer Token: {bearer_token}')
else:
    print(f'Error: {response.status_code} - {response.text}')

Replace your_access_key_id and your_api_secret with your actual Access Key id and Api Secret.

3. Run the script, and if successful, it will print the Bearer Token. You can then use this Bearer Token for subsequent API calls to m3ter.