Permalink
Fetching contributors…
Cannot retrieve contributors at this time
166 lines (117 sloc) 6.89 KB
---
parent: authorization
title: flows
---
# Authorization Flows <%= edit_link %>
<%= partial 'partials/toc' %>
## Generate `access_token`
The first thing you need to do before any request which requires authorization
is to grab a valid `access_token`. Depending on your application's needs you
either need an `application token` or a `user token`.
> Keep in mind that a user token can also be used for accessing public resources
as well, taken that it was generated containing the `public` permission in the
`scope` parameter.
### Application Token
An implementation of
<a href='http://tools.ietf.org/html/rfc6749#section-4.4'>client-credentials</a>,
allowing you to access **only** public resources.
Expires `2 weeks` upon creation.
The request signature of an application token request (`client_credentials`) is
the following:
<pre class="terminal">
POST https://www.<%= settings.domain %>/oauth2/token
</pre>
Name | Type | Value | Required | Description
----------------| ---------| --------------------| ---------| -----------
`client_id` | String | | Yes | The application client ID supplied by <%= settings.site_name.capitalize %>
`client_secret` | String | | Yes | The application client secret supplied by <%= settings.site_name.capitalize %>
`grant_type` | String | `client_credentials`| Yes | The grant type of the request. Value must be `client_credentials`.
`scope` | String | `public` | Yes | Only `public` permission is allowed in application_tokens
### User Token
It grants access to user resources and is generated in two steps. Expires in **a day** since its creation.
#### Step 1 - Get an <a href="http://tools.ietf.org/html/rfc6749#section-4.1">authorization code</a>
The request signature of an authorization code request is the following:
<pre class="terminal">
GET https://www.<%= settings.domain %>/oauth2/authorizations/new
</pre>
Name | Type | Value | Required | Description
----------------| ---------| ------| ----------| -----------
`client_id` | String | | Yes | The application client ID supplied by <%= settings.site_name.capitalize %>
`redirect_uri` | String | | Yes | The redirect uri of the application
`response_type` | String | `code`| Yes | The type of the response. Value must be `code`.
`scope` | String | `public`, `favorites`, `notifications`| Yes | The space separated set of permissions your application wishes
If you perform the above request the user will get to see a screen prompting to
authorize your application to access the resources you specified in the
<span class="label label-default">scope</span> parameter.
Given that the user granted your application the requested permissions, you are
then redirected to:
<pre class="terminal">
https://your_redirect_uri?code=a_valid_authorization_code
</pre>
Otherwise you will get redirected to:
<pre class="terminal">
https://your_redirect_uri?error=access_denied
</pre>
> Keep in mind that the code will be url-encoded. Please url-decode it before supplying it
to the library performing HTTP requests, as the library may url-encode it again, rendering it invalid.
#### Step 2 - Exchange the authorization code for an `oauth_token` and a refresh token
The request signature of an access token request is the following:
<pre class="terminal">
POST https://www.<%= settings.domain %>/oauth2/token
</pre>
Name | Type | Value | Required | Description
----------------| -------| --------------------|----------| -----------
`client_id` | String | | Yes | The application client ID supplied by <%= settings.site_name.capitalize %>
`client_secret` | String | | Yes | The application client secret supplied by <%= settings.site_name.capitalize %>
`redirect_uri` | String | | Yes | The redirect uri of the application
`grant_type` | String | `authorization_code`| Yes | The grant type of the request. Value must be `authorization_code`.
`code` | String | | Yes | The authorization code obtained
If the request was successful, the response contains JSON in the following form:
~~~ javascript
{
"access_token": "your_access_token",
"refresh_token": "your_refresh_token",
"token_type": "bearer",
"expires_in": 3599
}
~~~
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-triangle"></i>
expires_in field is counted in seconds.
</div>
## Consume `access_token`
There are 2 ways to specify your `access_token` in a request.
###### 1. As a parameter
<%= render_code_from_file "authentication/#{flavor}/example_search_request_parameter" %>
###### 2. As a header
<%= render_code_from_file "authentication/#{flavor}/example_search_request_header" %>
> Mind not to use both ways at the same time.
## Renew `access_token`
Any API call with an expired `access_token` receives an HTTP `401 Unauthorized`
response.
### Application Token
If your application token you're using gets expired you have to get a new one in
the exact way you got the last one.
<pre class="terminal">
POST https://www.<%= settings.domain %>/oauth2/token
</pre>
Name | Type | Value | Required | Description
----------------| ---------| --------------------| ---------| -----------
`client_id` | String | | Yes | The application client ID supplied by <%= settings.site_name.capitalize %>
`client_secret` | String | | Yes | The application client secret supplied by <%= settings.site_name.capitalize %>
`grant_type` | String | `client_credentials`| Yes | The grant type of the request. Value must be `client_credentials`.
`scope` | String | `public` | Yes | Only `public` permission is allowed in application tokens
The above request will respond with an existing or a new application token. Notice that
in this case you don't need to exchange a refresh token for an application token.
### User Token
When a user token gets expired you need to exchange the refresh token
you've been given for a new valid token.
<pre class="terminal">
POST https://www.<%= settings.domain %>/oauth2/token
</pre>
Name | Type | Value | Required | Description
----------------| ---------| --------------------| ---------| -----------
`client_id` | String | | Yes | The application client ID supplied by <%= settings.site_name.capitalize %>
`client_secret` | String | | Yes | The application client secret supplied by <%= settings.site_name.capitalize %>
`refresh_token` | String | | Yes | The `refresh_token` obtained in an earlier step
`grant_type` | String | `refresh_token` | Yes | The grant type of the request. Value must be `refresh_token`.