Authentication and Authorization - m3ter Documentation

OAuth 2.0 Authentication

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

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.