Getting Started with the Metry as a Developer

This guide explains how you get started using with the Metry’s API for one of your customers.

Where can I find detailed API documentation? http://docs.metry.apiary.io/

Before you get started

Create a developer account, and a new client and make sure you have

  • client_id
  • client_secret
  • redirect_uri

Getting access to your customer’s data

Metry uses the Oauth Authorization Code flow to allow users to authorize a 3rd party application to access their data on the Metry platform, this will require the client id and secret you obtained as part of the developer sign up process.

It contains the following steps

1. Send the user to the login page to authorise your application

Send the user to the Metry authorization service to authorize access to their data. The {scope} parameter should be “basic” in most cases. The {state} parameter is optional and used to include custom information that you would like Metry to include when redirecting the user back to your app.

https://app.metry.io/id/oauth/authorize?client_id={client_id}&redirect_uri={response_uri}&grant_type=authorization_code&response_type=code&state={state}&scope={scope}

2. Receive authorization token

If the user chooses to approve access our service redirects the user to the uri listed in the redirect_uri param along with an authorization token.

{response_uri}?code={authorization_token}&state=emAuth Save & Exit

3. Request a refresh token and an access token

With an authorization token you can now request an access token and a refresh token which can be used to “refresh” the access token when it expires (after 60 minutes). The refresh token should be stored on your end with the same security in mind as a password.

Send a POST to

https://app.metry.io/oauth/token

with the following data

{
"grant_type" : "authorization_code",
"code" :{authorization_token},
"client_id":{id},
"Client_secret": {secret},
"redirect_uri" : {response_uri}
}

The response will contain

{
"access_token": {access_token},
"expires_in": 3600,
"token_type": "Bearer",
"scope": "basic",
"refresh_token": {refresh_token}
}

The received access token can be used to request data on the customer’s behalf from the API. The access_token itself will expire after 1 hour at which point the refresh_token should be used to fetch a new access_token, just as any other OAuth2 implementation.

4. Refresh the access token

Once you have a refresh token it may be used to fetch a new access token with it expires.

Send a POST request to

https://app.metry.io/oauth/token

With the following data

{
"client_id":{id},
"client_secret":{secret},
"grant_type":"refresh_token",
"refresh_token":{refresh_token}
}

The response will contain the following
{
"access_token": {access_token},
"expires_in": 3600,
"token_type": "Bearer",
"scope": "basic"
}

Why can’t I use a customer’s personal Access token

There are a number of issues with allowing 3rd parties access to a user’s personal access token (or bearer token as the they are often called). Bearer tokens function similarly to cash (or bearer bonds) in that whoever is in possession of the token (or knows what it is) is considered to be it’s owner. This gives us no practical way of verifying who is accessing the data and no practical way to revoke access to a 3rd party if the customer later chooses to stop a 3rd party from accessing their data.

Personal tokens also have a different access level than access tokens generated from refresh tokens, they have access to make changes that affect how much the customer is billed every month. This combined with the extra security layer that Oauth provides means we can not allow 3rd parties to use customer’s personal access tokens.