# Authorization

Every request to the Tali API will require an access_token. This is obtained on a per-user basis using OAuth 2.0. If you've worked with an OAuth API before, this should be familiar to you.

Before getting started, be sure you've obtained your client_id and client_secret from us. If not, reach out to us at [email protected] and tell us a little about your project.

# OAuth Flow

Below is the tl;dr for a typical OAuth 2.0 flow.

1. Send your user to the Tali authorize page with your client specific query parameters such as client_id, redirect_uri, state, and a response_type of code.
2. The user signs in to Tali, is redirected to the authorize page, clicks "Accept", and is then redirected back to your redirect_uri with a code as a query parameter.
3. Back on your system, send this code with your client_id and client_secret back to us to receive the coveted access_token along with other goodies.

# Access Tokens

# Request Code

First, you gotta send the user to our Tali authorization page where they'll click "Accept" or "Cancel". Then we'll redirect them back to the site you provided with redirect_uri with a code that you'll then use to request an access_token.

GET /oauth/authorize HTTP/1.1
Content-Type: application/json
{
  response_type: 'code',
  client_id: 'your-client-id',
  redirect_uri: 'http://yoursite.com/callback',
  state: '<optional>'
}

# Request Access Token

Trade the code from the previous step for an access_token. You'll also need to provide your client_id and client_secret.

POST /oauth/token HTTP/1.1
Content-Type: application/json
{
  grant_type: 'authorization_code',
  code: 'the-code-you-just-got',
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  redirect_uri: 'http://yoursite.com/callback',
}

# Access Token Response

Alas, bounty! Persist the user's access_token and refresh_token in your system and send the access_token in the header of every Tali API request.

{
  "access_token": "MBEehXv6KQcLH39ObZ8F6FVhQsJ2Bcf7XTf64",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  "expires_in": "86400",
  "token_type": "Bearer"
}

# Refresh Tokens

The access_token will expire after 86400 seconds – 24 hours. When this happens, send back the refresh_token to get a fresh access_token.

POST /oauth/token HTTP/1.1
Content-Type: application/json
{
  grant_type: 'refresh_token',
  refresh_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9',
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  redirect_uri: 'http://yoursite.com/callback',
}