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 OAuth2 Client ID and Client Secret. The Secret should be kept in a safe place and not shared with anyone.

To register your app, first you need to sign up to Spreaker. Once you’re logged in you can click on the button below to enable the Developers section on your account, from where you’ll be able to manage your applications.

ENABLE DEVELOPER TOOLS IN YOUR SPREAKER ACCOUNT »

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:

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

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

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

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:

Example

curl -X POST -F "grant_type=authorization_code" -F "client_id=1234567890" -F "client_secret=1234567890" -F "redirect_uri=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"
}

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:

Example

curl -X POST -F "grant_type=refresh_token" -F "client_id=1234567890" -F "client_secret=1234567890" -F "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"
}

Invalidating an Access Token

To invalidate an access token so that it cannot be used for any further activity, make an HTTP DELETE request to the following API endpoint:

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

This endpoint requires the token you need to invalidate to be provided in the Authorization: Bearer HTTP header.

The response body is an empty object.

{"response":[]}

Example

curl -X DELETE -H "Authorization: Bearer OAUTH-TOKEN" https://api.spreaker.com/oauth2/token

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

Invalidating an access token

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