Interested in working with us? We offer a superb REMOTE work opportunity for a WEB ENGINEER.

Click here to find out more.

Authentication

  1. Registering Your App
  2. The Login Dialog
  3. Cancelled Login
  4. Client-Side Token
  5. Server-Side Token
  6. Exchanging Code for an Access Token
  7. Refreshing an Access Token
  8. Final Recap

Registering Your App

First, you’ll need to register your application. Every registered OAuth application is assigned a unique Application ID and Secret. The Secret should be kept in a safe place and not shared with anyone.

To register your app, send an email to dev@spreaker.com - a Spreaker engineer will quickly reply with the full instructions. This manual process will be replaced by an online form as soon as Spreaker for Developers moves to General Availability.

If it’s the first time you’re working with OAuth2 don’t worry, in this guide we don’t assume that you have any previous knowledge of the process, so just continue reading and everything will be explained. If you already know how it works, you can jump straight to the Final Recap.

The Login Dialog

If the user is not logged into your app or not logged into Spreaker, you can use the login dialog to prompt them to do both. If they aren’t logged into Spreaker, they’ll be prompted to log in and then go through the login process of your app. This is automatically detected, so you don’t need to do anything more to enable this behavior.

Your app must initiate a redirect to an endpoint which will display the login dialog:

https://www.spreaker.com/oauth2/authorize?client_id=APP_CLIENT_ID&response_type=RESPONSE_TYPE&state=CSRF_PROTECTION&scope=basic&redirect_uri=YOUR_REDIRECT_URI

This endpoint has the following required parameters:

Parameter Required Description
client_id yes The client ID of your OAuth2 application
response_type yes The grant type. Valid values are: code, token. See Server-Side Token or Client-Side Token.
state yes An arbitrary, unique string created by your app to guard against Cross-site Requests Forgery
scope yes A space-separated list of scopes you are requesting. At the moment the only available scope is basic.
redirect_uri yes The URL that you want to redirect the user logging in back to. It will capture the result of the authentication flow.

At this point in the login flow, the user will see the login dialog and have a choice of whether to cancel or to let the app access their data. In all cases, the browser returns to the app, and response data indicating whether someone connected or cancelled is included.

When your app uses the redirect method as above, the redirect_uri your app returns to will be appended with URL parameters or fragments (as per the chosen response_type), which must be captured.

Cancelled Login

If the user chooses CANCEL in the login dialog, the browser will be redirected to the following page:

YOUR_REDIRECT_URI?state=CSRF_PROTECTION&error=access_denied&error_description=The+user+denied+access+to+your+application
Parameter Description
state The csrf protection string you specified when starting the login dialog
error The error code
error_description The human-readable error description

Client-Side Token

This section describes how to handle the login dialog response when you set the response_type parameter to token. This is useful if you need an OAuth2 token to be used only on the client side. Because client-only applications cannot safely store the OAuth application secret, this token is not refreshable and usually has a shorter lifespan.

If the user chooses OK in the login dialog, the browser will be redirected to the following page:

YOUR_REDIRECT_URI#state=CSRF_PROTECTION&access_token=OAUTH2_TOKEN&expires_in=EXPIRES_IN&token_type=Bearer&scope=basic
Parameter Description
state The csrf protection string you specified when starting the login dialog
access_token The access token that can be used to authenticate the API call
expires_in The lifetime of the token, expressed in seconds
token_type The token type. Currently the supported value is Bearer
scope The space-separated list of scopes you specified when starting the login dialog
refresh_token The token that can be used to refresh the one being used once it has expired

Server-Side Token

This section describes how to handle the login dialog response when you set the response_type parameter to code. This is useful if you need an OAuth2 token that you can store on your server to make server-to-server API calls. This token can also be refreshed at any time without direct user interaction.

If the user chooses OK in the login dialog, the browser will be redirected to the following page:

YOUR_REDIRECT_URI?state=CSRF_PROTECTION&code=OAUTH2_CODE
Parameter Description
state The csrf protection string you specified when starting the login dialog
code The code that you should pass to your server that will be exchanged for a valid token

When this is received, it has to be exchanged for an access token using an API endpoint. The call will need to be server-to-server, since it involves your app secret (your app secret should never end up in client code!).

Exchanging Code for an Access Token

To exchange your code for a valid access token, make an HTTP POST request to the following API endpoint:

POST https://api.spreaker.com/oauth2/token

This endpoint has the following required parameters:

Parameter Required Description
grant_type yes Value: authorization_code
client_id yes The client ID of your OAuth2 application
client_secret yes The client secret of your OAuth2 application
redirect_uri yes The same redirect URL you used to configure the login dialog
code yes The code you received from the login dialog

Example

curl -X POST -F "grant_type=authorization_code" -F "client_id=1234567890" -F "client_secret=1234567890" -F "redirect_url=http://localhost" -F "code=foobar" https://api.spreaker.com/oauth2/token

The response body is a JSON object containing the following data:

{
    "access_token":"1234567890",
    "expires_in":315360000,
    "token_type":"Bearer",
    "scope":"basic",
    "refresh_token":"1234567890"
}
Parameter Description
access_token The access token that can be used to authenticate the API call
expires_in The lifetime of the token, expressed in seconds
token_type The token type. Currently the supported value is Bearer
scope The space-separated list of scopes you specified when starting the login dialog
refresh_token The token that can be used to refresh the one being used once it has expired

Refreshing an Access Token

Once your access token expires, you can refresh it for a new one that will have the same scope. In order to refresh your token, make an HTTP POST request to the following API endpoint:

POST https://api.spreaker.com/oauth2/token

This endpoint has the following required parameters:

Parameter Required Description
grant_type yes Value: refresh_token
client_id yes The client ID of your OAuth2 application
client_secret yes The client secret of your OAuth2 application
refresh_token yes The refresh token that was associated with your OAuth token

Example

curl -X POST -F "grant_type=refresh_token" -F "client_id=1234567890" -F "client_secret=1234567890" "refresh_token=1234567890" https://api.spreaker.com/oauth2/token

The response body is a JSON object containing the following data:

{
    "access_token":"1234567890",
    "expires_in":315360000,
    "token_type":"Bearer",
    "scope":"basic",
    "refresh_token":"1234567890"
}
Parameter Description
access_token The new access token that can be used to authenticate the API call
expires_in The lifetime of the token, expressed in seconds
token_type The token type. Currently the supported value is Bearer
scope The space-separated list of scopes
refresh_token TThe token that can be used to refresh the one being used once it has expired

Final Recap

#### Login dialog URL

https://www.spreaker.com/oauth2/authorize?client_id=APP_CLIENT_ID&response_type=RESPONSE_TYPE&state=CSRF_PROTECTION&scope=basic&redirect_uri=YOUR_REDIRECT_URI

Exchanging code for an access token

POST https://api.spreaker.com/oauth2/token?client_id=APP_CLIENT_ID&client_secret=APP_CLIENT_SECRET&grant_type=authorization_code&redirect_uri=YOUR_REDIRECT_URI&code=CODE

Refreshing an access token

POST https://api.spreaker.com/oauth2/token?client_id=APP_CLIENT_ID&client_secret=APP_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRES_TOKEN