## 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](https://docs.m3ter.com/guides/authenticating-with-the-platform/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:
   
   ```python
   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.