MachineMetrics

The MachineMetrics Developer Hub

Welcome to the MachineMetrics developer hub. You'll find comprehensive guides and documentation to help you start working with MachineMetrics as quickly as possible. Let's jump right in!

OAuth Authorization

All third party applications must be authorized through the OAuth protocol.

Creating an OAuth application

To get started with writing an OAuth application for MachineMetrics, contact support@machinemetrics.com to register your application. Include:

  • The name of your application.
  • The redirect URI of your application (more information below).
  • The MachineMetrics user that is responsible for managing this application, if applicable.

Support will return a client id and client secret that identify your application. Keep these credentials safe. In particular, the client secret should never be exposed and cannot be recovered by MachineMetrics if lost. We can generate new credentials for you, but previous credentials will stop working in that instance.

MachineMetrics only support the authorization code grant type. If this grant type is not suitable for your application, consider using API keys instead.

Implementing the Authorization Code Grant

This standard grant type flows through several basic steps:

  • Users are redirected to MachineMetrics to login and authorize
  • Users are redirected back to your application by MachineMetrics
  • Your application accesses the MachineMetrics API with the provided access token

1. Users are redirected to MachineMetrics

GET https://login.machinemetrics.com/oauth/authorize

Parameters

Name
Description

response_type

Required. Must always be set to "code".

client_id

Required. The client ID you received from MachineMetrics when you registered your application.

redirect_uri

Required. The URL users will be redirected back to after authorization. Must match one of the redirect URLs registered to your application. See details about redirect urls.

scope

A space-delimited list of scopes that your application is requesting access for. Users will be prompted to allow access for each scope. If a scope has been authorized by a previous authorization grant flow, the user will not be prompted again.

state

A random string used to protected against cross-site request forgery attacks.

2. Users are redirected back to your application

After the user accepts or rejects your request, MachineMetrics will redirect them back to your application. If the request was denied or another error occurred in the process, the query string of the redirect will include an error and error_description parameter describing the result.

If the request was accepted, the query string of the redirect will include a temporary code parameter and a state parameter. The state parameter will match the state value your application provided in the original authorization request. If the states don't match, the request did not come from your application and the rest of the authorization process should be stopped.

Your application needs to issue a web request to exchange the code for an access token.

POST https://login.machinemetrics.com/oauth/token

The web request body must be x-form-urlencoded.

Parameters

Name
Description

grant_type

Required. Must always be set to "authorization_code".

client_id

Required. The client ID you received from MachineMetrics when you registered your application.

client_secret

Required. The client secret you received from MachineMetrics when you registered your application.

redirect_uri

Required. The same redirect_uri provided in step 1.

code

Required. The code you received in the response from step 1.

Reponse

The token request will send back an application/json response with the following form:

{
  "access_token": "at-3fd2bb4d7f5046e9a8b807846e45dc4e",
  "token_type": "bearer",
  "scope": "user,operator"
}

3. Use the access token

The access token you get back is your credential for accessing MachineMetrics APIs on behalf of the user. The access token should be passed in the Authorization header of each request.

Authorization: Bearer OAUTH-TOKEN

If the Authorization header cannot be used for some reason, then access tokens can be passed in the query string using the access_token parameter. This use is discouraged.

GET https://api.machinemetrics.com/locations?access_token=...

Redirect URLs

The redirect_uri parameter in OAuth is required by MachineMetrics. Each authorization grant request must provide a redirect URL to return a user to after authorization. The URL must exactly match the URL that your application was registered with, or match a subpath of that URL. You may register multiple URLs with your application.