4.0.0 com.m3ter sdk-java-core 0.5.0 m3ter API If you are using Postman, you can: - Use the **Download** button above to download the m3ter Open API spec JSON file and then import this file as the **m3ter API Collection** into your Workspace. See [Importing the m3ter Open API](https://www.m3ter.com/docs/guides/m3ter-apis/getting-started-with-api-calls#importing-the-m3ter-open-api) in our main user Documentation for details. - Copy this link: [m3ter-Template API Collection](https://www.datocms-assets.com/78893/1672846767-m3ter-template-api-collection-postman_collection.json) and use it to import the **m3ter-Template API Collection** into your Workspace. See [Importing the m3ter Template API Collection](https://www.m3ter.com/docs/guides/m3ter-apis/getting-started-with-api-calls#importing-the-m3ter-template-api-collection) in our main user Documentation for details. --- # Introduction The m3ter platform supports two HTTP-based REST APIs returning JSON encoded responses: - The **Ingest API**, which you can use for submitting raw data measurements. _(See the [Submit Measurements](https://www.m3ter.com/docs/api#tag/Measurements/operation/SubmitMeasurements) endpoint in this API Reference.)_ - The **Config API**, which you can use for configuration and management. _(All other endpoints in this API Reference.)_ ## 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](https://www.m3ter.com/docs/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 authorise all subsequent API requests. > Warning: 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: ```bash 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: ```json { "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: ```bash 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. ## Submitting Personally Identifiable Information (PII) **IMPORTANT!** Under the [Data Processing Agreement](https://www.m3ter.com/docs/legal/dpa), the only fields permissible for use in submitting any of your end-customer PII data in m3ter are the `name`, `address`, and `emailAddress` fields on the **Account** entity - see the details for [Create Account](https://www.m3ter.com/docs/api#operation/PostAccount). See also section 4.2 of the [Terms of Service](https://www.m3ter.com/docs/legal/terms-of-service). ## Rate and Payload Limits ### Config API Request Rate Limits See [Config API Limits](https://www.m3ter.com/docs/guides/m3ter-apis/config-api-limits). ### Data Explorer API Request Rate Limits See [Data Explorer Request Rate Limits](https://www.m3ter.com/docs/guides/m3ter-apis/config-api-limits#date-explorer-request-rate-limits). ### Ingest API Request Rate and Payload Limits See [Ingest API Limits](https://www.m3ter.com/docs/guides/m3ter-apis/ingest-api-limits) for more information. ## Pagination **List Endpoints** API endpoints that have a List resources request support cursor-based pagination - for example, the `List Accounts` request. These List calls support pagination by taking the two parameters `pageSize` and `nextToken`. The response of a List API call is a single page list. If the `nextToken` parameter is not supplied, the first page returned contains the newest objects chronologically. Specify a `nextToken` to retrieve the page of older objects that occur immediately after the last object on the previous page. Use `pageSize` to limit the list results per page, typically this allows up to a maximum of 100 or 200 per page. **Search Endpoints** API endpoints that have a Search resources request support cursor-based pagination - for example, the `Search Accounts` request. These Search calls support pagination by taking the two parameters `pageSize` and `fromDocument`. The response of a Search API call is a single page list. If the `fromDocument` parameter is not supplied, the first page returned contains the newest objects chronologically. Specify a `fromDocument` to retrieve the page of older objects that occur immediately after the last object on the previous page. Use `pageSize` to limit the list results per page, typically this allows up to a maximum of 100 or 200 per page. Default is 10. ## API Quick Start See [Getting Started with API Calls](https://www.m3ter.com/docs/guides/m3ter-apis/getting-started-with-api-calls) for detailed guidance on how to use our API to: - Create a Service User and add permissions. - Generate access keys for the Service User. - Use basic authentication to obtain a Bearer Token. For further guidance, also see [Creating and Configuring Service Users](https://www.m3ter.com/docs/guides/organization-and-access-management/managing-users/creating-and-configuring-service-users). ## Other Languages If you want to work with the m3ter REST APIs using other languages such as: - Python - JavaScript - C++ Please see the [Developer Tools](https://www.m3ter.com/docs/guides/developer-tools) topic in our main documentation for information about available SDKs. # Authentication <!-- ReDoc-Inject: <security-definitions> --> https://www.m3ter.com Apache-2.0 M3ter sdks@m3ter.com scm:git:git://github.com/m3ter-com/m3ter-sdk-java.git scm:git:git://github.com/m3ter-com/m3ter-sdk-java.git https://github.com/m3ter-com/m3ter-sdk-java com.fasterxml.jackson.core jackson-core 2.18.2 compile com.fasterxml.jackson.core jackson-databind 2.18.2 compile com.google.errorprone error_prone_annotations 2.33.0 compile org.jetbrains.kotlin kotlin-stdlib-jdk8 1.8.0 compile com.fasterxml.jackson.core jackson-annotations 2.18.2 runtime com.fasterxml.jackson.datatype jackson-datatype-jdk8 2.18.2 runtime com.fasterxml.jackson.datatype jackson-datatype-jsr310 2.18.2 runtime com.fasterxml.jackson.module jackson-module-kotlin 2.18.2 runtime org.apache.httpcomponents.core5 httpcore5 5.2.4 runtime org.apache.httpcomponents.client5 httpclient5 5.3.1 runtime