Piano uses OAuth so you can authenticate and authorize your applications and safely gain the credentials of your user’s information.

Basic Workflow

  1. Authorization Request: A Client Application must first obtain authorization from the Resource Owner before it can access a protected resource.
  2. Grant Request: The Client Application then exchanges the access grant for an access token.
  3. Access Token: Lastly, the Client Application accesses the protected resource by presenting the access token to the resource server.
   +--------+                                  +---------------+
   |        |--(1a)-- Authorization Request -->|   Resource    |
   |        |                                  |     Owner     |
   |        |<-(1b)--- Authorization Granted --|               |
   |        |                                  +---------------+
   |        |
   |        |                                  +---------------+
   |        |--(2a)----- Access Grant--------->| Authorization |
   | Client |                                  |     Server    |
   |        |--<-(2b)----- Access Token -------|               |
   |        |                                  +---------------+
   |        |
   |        |                                  +---------------+
   |        |--(3a)------ Access Token ------->|    Resource   |
   |        |                                  |     Server    |
   |        |<-(3b)---- Protected Resource ----|               |
   +--------+                                  +---------------+


1a. The first step is to Generate a link for login to retrieve your client ID and client secret. It should look like this:


In some cases, one of the implementation requirements is to disable the ability to create an account. To achieve that, you can add additional parameter to the login URL “disable_sign_up”:


1b. After the user has logged in - he will be redirected to the url specified in the previous step with an additional “code” parameter

2a. Using that code - request access token, so that the user can be validated and an API requests could be executed in the name of that user by making a POST request to


With the following parameters:

  • client_id - application ID
  • client_secret - OAuth secret
  • code - the code parameter received in the previous step
  • grant_type=authorization_code
  • redirect_uri - the same REDIRECT_URI parameter used in the first step

2b. If the request is successful - the response should look like the following JSON string:

  "code" : 0,
  "ts" : 1469126715,
  "access_token" : "800842327c72f4a497e6ca13607ed18c",
  "data" : {
    "access_token" : "800842327c72f4a497e6ca13607ed18c",
    "expires_in" : 2678400,
    "token_type" : "bearer"
  "token_type" : "bearer",
  "expires_in" : 2678400

3a. API requests need to be executed with an Authorization header like this: Authorization: Bearer <ACCESS_TOKEN> Where ACCESS_TOKEN - is the access_token parameter received in the previous step. To make any consecutive requests, the access_token needs to be saved in the user's session.

3b. To check if user has access - use the following method:


This request will return the JSON access object similar to this:

  "code" : 0,
  "ts" : 1469127375,
  "access" : {
    "access_id" : null,
    "granted" : false,
    "resource" : null,
    "user" : null,
    "expire_date" : 1469127374

If user is entitled to access this resource, the “granted” parameter will be set to “true”

Alternatively, get the list of the current access objects using the following method:


This method will return an array of access objects in the same format as in the previous example.