OAuth Authorization

OAuth 2.0 is the industry-standard protocol for authorization. Users receive an access token using one of the grant types listed below. This token can be used to authenticate against all future calls to the API. Tokens are short lived, but refresh tokens allow you to automatically create a new one without needing to sign in again.

Grant Types

Option 1: SSO for server-side applications (Grant Type = authorization_code)

When users need to log in to your application, send them to a url like this. The user can login, and we will then redirect them to the specified url, with a code attached. Once you have this code, post it to the /token endpoint to get your access token. This token should be in the authorization header of all requests.

ex body:

 
{
    "grant_type":"authorization_code",
    "client_id" : "BA779C49-4D93-4785-9596-25805A24C5DC",
    "client_secret" : "4AD3CE00-8ED5-4F0A-A979-ACE64A15207C",
    "code" : "kfVaG3IPc7hb2Vi2pgOI_9GNBSJurR6PFdXF2LesNNDyiF1XDwQHgEtkMNwlH7OB9DL8k1bbWHaHab76mw6qOeM9V2sy36rRZHYSahMBXPo%3D"
}

Option 2: SSO for client-side applications (Grant Type = implicit)

If your application runs client-side, you are expected to use the implicit grant type. It is very similar to option 1, except the url is a little different (it looks like this), we return the access token directly, instead of the code, and finally, the token will not have a refresh token attached. This protects us from your token getting out in the open.

Option 3: Local Login (Grant Type = password)

For mobile applications, non-browser based applications, or if you just don't like our SSO page, we also support the grant type 'password'. This means you post the client secret, client id, username and password directly to the /token endpoint and get back an access token.

ex body:

 
{
    "grant_type":"password",
    "client_id" : "BA779C49-4D93-4785-9596-25805A24C5DC",
    "client_secret" : "4AD3CE00-8ED5-4F0A-A979-ACE64A15207C",
    "username" : "jsmith",
    "password" : "password123"        
}

Option 4: Application Login (Grant Type = client_credentials)

Not all applications require authentication. If you have an application, that wants to use the api, but doesn't want to ask your users to sign in, then you want the client_credentials grant type. Just send your client_id and client_secret to the token endpoint, and get a token back for your application itself.

ex body:

 
{
    "grant_type":"client_credentials",
    "client_id" : "BA779C49-4D93-4785-9596-25805A24C5DC",
    "client_secret" : "4AD3CE00-8ED5-4F0A-A979-ACE64A15207C"       
}

Option 5: Refresh Token (Grant Type = refresh_token)

Access tokens are short lived, by design. Rather than kicking the user out when the session expires, we support the refresh token grant type. For all work flows, except implicit (option 2), the access token will come with a refresh token. When the access token expires, post the refresh token back to the /token endpoint. We will return a new access token with a fresh refresh token, allowing your users to stay logged in between sessions, without compromising security.

ex body:

 
{
    "grant_type":"refresh_token",
    "client_id" : "BA779C49-4D93-4785-9596-25805A24C5DC",
    "client_secret" : "4AD3CE00-8ED5-4F0A-A979-ACE64A15207C",
    "refresh_token" : "C0fJeyBPMXOTuSThwUh2S0Vq83ezkMTjoIDroK9LCNCy7jscLkWXCvsuidxhF9t_FGHpo-_gUgi5J7eUejpfEgw3SQXHstBaDR0eauY2s3g%3d"
}