There are two types of tokens that each serve slightly different purpose. The code based access token is good for server-to-server calls as it requires a server to manage a secret key. The token based access token is for client-to-server API calls. Some API calls require the code access token to prevent server based API calls from running via a browser.

Authorization code

Code based access tokens are granted using response_type = code.

These access tokens are long lived (1 year) and must be refreshed once expired. They are for server-to-server requests and should not be shared with clients.

This method relies on the redirect URI. The login flow is as follows: User login -> redirect URI -> Exchange code for access token.

  • code - the grant code
  • state - the state you pass to prevent Cross Site Scripting (optional, null by default)

The redirect_uri will receive a code via a query string like so:

Location: "http://mysite.com/auth/callback?code=[CODE]&state=[STATE]"

The following is a curl example showing how a server might exchange the single use code for a long lived access token:

curl -XPOST 'https://account.y8.com/oauth/token' -d 'grant_type=authorization_code' -d 'client_id=[APP_ID]' -d 'client_secret=[APP_SECRET]' -d 'code=[CODE]'

Implicit grant (token)

Token based access tokens are granted using response_type = token.

These access tokens are short lived (6 hours) and designed to be discard and refreshed with each return to an application.

This method can be done client side and does not require any page navigations. Using the JS SDK, a callback will return the following:

  • access_token - the access_token
  • expires_in - number of seconds before the token expires
  • token_type - the type of the token (Bearer by default)
Location: "http://mysite.com/auth/callback#access_token=[access_token]&expires_in=21600&token_type=bearer"

Passing an access token using a request header

curl -XGET -H 'Authorization: Bearer [access_token]' 'https://account.y8.com/api/profile'

Passing an access token using a query parameter

This way is less secure than using a request header to authorize.

curl -XGET -H 'https://account.y8.com/api/profile?access_token=[access_token]'

For more details about the OAuth protocol, see the specification  rfc6749