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 authorisation service to authorise access to their data.

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

    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

    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.