Skip to main content

Authentication

Requests made to the MachineMetrics API endpoints must be authenticated. This is the case for both our REST as well as our GraphQL endpoints.

In both cases, our system leverages Bearer tokens in the Authorization header as a means to authenticate. This guide walks through the steps required to create a valid Bearer token, or more specifically an API Key access token. We will also cover the concept of Scope, how to properly manage secrets like your API Keys, and what to do when your use case might require alternative options for an access token.

Acquiring an API Key​

  1. Navigate to https://app.machinemetrics.com/settings/api-keys.
  2. Note that each API Key grants access rights for the company in MachineMetrics where the key was created. If you have access to multiple companies, ensure that you are creating an API Key for the correct one.
  3. Start by clicking Create API Key in the upper right.
  4. Name the key something relevant to the task. It is best practice to have separate keys for separate use cases.
  5. Choose the appropriate scopes and click "Save Changes".
  6. Copy your API Key from the screen provided. Store it somewhere safe.

API Keys are passwords. Anyone who has this can access the data it can access. Treate them with care.

Scopes​

Each endpoint requires a certain level of permission to access them. All GraphQL queries and the Production Reporting endpoints are read-only and can be accessed with API Key access tokens granted to reporting scope. Other endpoints that access more sensitive data or allow for information to be modified (mutated) require other scopes.

See the AUTHORIZATIONS section for each endpoint in the REST API reference for information on required scopes.

Managing API Keys​

There are a few best practices which should be followed when managing your API Keys.

API Keys are Passwords​

As noted before, API Keys are effectively passwords. They are secrets and must be treated with care.

  • Do not share API Keys with people or systems who should not have access to the data those API Keys can access.
  • Do not store API Keys on systems that unauthorized people can access.
  • Do not transfer API Keys using insecure mechanisms.
  • Do delete API Keys when you're done with them.

Adopt the Practice of Least Priviledge​

API Keys should only be granted the permissions necessary to complete the task. While you are only shown the API Key one time, you can adjust granted scopes for that API Key at any time.

Use Separate Keys for Separate Purposes​

API Keys are free! Create as many as you need. It is recommended that each use case you create has a separate API Key. This allows for more fine-grained control over its granted scopes, but also allows for more targeted management in situations of abuse or loss.

If you lose an API Key or are not certain that it is secure, deleting an API Key that is used for multiple systems can have a larger impact than one that is just used for a single system.

Similarly, MachineMetrics is a multi-tenant cloud. If it is detected that an API Key is being abused - intentionally or not - and that is having a negative impact on the integrity of the MachineMetrics infrastructure, that key may be temporarily or permanently disabled. By creating separate keys when doing experimentation, for example, certain protections such as rate limiting will only affect the experiment and not your production systems using other keys.

Examples​

When making requests to the MachineMetrics API endpoints, you must add an Authorization header to your request. The value of the Authorization header comes in the form of a Bearer token.

While most uses of the MachineMetrics APIs will take advantage of developer tools and libraries to make web requests, the most simplistic examples can be provided using cURL to illustrate the general concept. Below are examples of queries to both our GraphQL as well as our Production Reporting endpoints.

Replace INSERT_API_KEY_HERE with the API Key acquired earlier.

REST
curl -H "Authorization: Bearer API-KEY" https://api.machinemetrics.com/reports/production

curl 'https://api.machinemetrics.com/reports/production' \
  -H 'Authorization: Bearer INSERT_API_KEY_HERE' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-raw '{"startDay":"2022-07-15","endDay":"2022-07-16","data":[{"metric":"utilizationRate"}]}'
GraphQL
curl 'https://api.machinemetrics.com/graphql' \
  -H 'authorization: Bearer INSERT_API_KEY_HERE' \
  -H 'content-type: application/json' \
  --data-raw '{"operationName":null,"variables":{},"query":"{\n  machines {\n    name\n  }\n}"}'

Alternatives to API Keys​

API Key access tokens are the only documented mechanism for accessing data through the MachineMetrics APIs. If you have use cases where this is not a viable or ideal approach, please contact support@machinemetrics.com for details on possible alternatives.