Authenticating with OAuth

All our API endpoints are designed to work only when a user is authenticated. We identify this user based on the access token you pass with each request. To generate a user access token, you must first request access to act on the user’s behalf through a flow based on the OAuth 2.0 authorization framework. Once you have a valid token, include the header Authorization: Bearer {token} in each request.

Start the OAuth flow

To start the OAuth flow and request user access, send a user to our OAuth page (https://www.redacted.com/oauth/) with parameters:

Here is an example request to the OAuth page:

https://www.redacted.com/oauth/?

client_id={YOUR_CLIENT_ID}&

redirect_uri={YOUR_REDIRECT_URI}&

response_type=code&

scope=boards:read,pins:read&

state={YOUR_OPTIONAL_STRING}

If the user is logged in when clicking on the OAuth link, they will see a page where they can approve access for your app for the scopes you’re requesting. If the user is not logged in, they will be asked to log in.

Receive the access code with your redirect URI

Once the user authorizes your app, they will be sent to your redirect URI. We will add the following parameters as we make the call to your redirect URI:

A redirect URI such as https://www.example.com/oauth/redacted/oauth_response/ will result in a callback request like: https://www.example.com/oauth/redacted/oauth_response/?code={CODE}&state={YOUR_OPTIONAL_STRING}

Exchange the code for an access token

(OAuth 2.0: Access Token Request/Response)

Once you have received the code to your redirect URI, you can exchange it for an access token by making a POST request to our access token endpoint with a request body and content type of application/x-www-form-urlencoded:

https://api.redacted.com/v5/oauth/token

You must use HTTP Basic Authorization to properly authenticate your requests to this endpoint. Where username is expected, use client_id; where password is expected, use client_secret (aka App Secret or App Secret Key). Your request would then have a header of Authorization: Basic {base64 encoded string made of client_id:client_secret}.

For example:

You can use the following command in Linux/OSX systems to quickly get the base64 encoded string (replace with your unique client_id and client_secret, or store them as environment variables):

echo -n $client_id:$client_secret | base64

Required request body parameters:

Here's an example request to exchange a code for an access token:

curl -X POST https://api.redacted.com/v5/oauth/token

--header 'Authorization: Basic {base64 encoded string made of client_id:client_secret}'

--header 'Content-Type: application/x-www-form-urlencoded'

--data-urlencode 'grant_type=authorization_code'

--data-urlencode 'code={YOUR_CODE}'

--data-urlencode 'redirect_uri=http://localhost/'

If successful, the response you receive will contain an access token and refresh token with expiration times and relevant scope information. Here’s an example:

{

    "access_token": "{an access token string prefixed with 'foo-a'}",

    "refresh_token": "{a refresh token string prefixed with 'foo-r'}",

    "response_type": "authorization_code",

    "token_type": "bearer",

    "expires_in": 2592000,

    "refresh_token_expires_in": 31536000,

    "scope": "boards:read boards:write pins:read"

}

expires_in and refresh_token_expires_in are the lifetime (in seconds) for your access token and refresh token respectively. The token you receive should contain only the scopes requested during the "Start the OAuth flow" step. Attempting to use an access token after its lifetime has expired will result in an HTTP 401 status with a specific API error code 2.

You may generate a new access token at any point during the lifetime of the refresh token as described in ‘Refreshing an access token’ below. Once the refresh token lifetime has expired you will need to explicitly request access again by starting the OAuth flow from the beginning.

Refreshing an access token

(OAuth 2.0 link: Refreshing an Access Token)

Access tokens expire within 30 days (2592000 seconds) of being issued. Refresh tokens last for 365 days (31536000 seconds).

Get a new access token by calling Generate OAuth access token, using HTTP Basic Authorization.

Where username is expected, use client_id; where password is expected, use client_secret (aka App Secret or App Secret Key).

Your request would then have a header of 'Authorization: Basic {base64 encoded string made of client_id:client_secret}'.

Required request body parameters:

Here's an example request for refreshing an access token:

curl -X POST https://api.redacted.com/v5/oauth/token

--header 'Authorization: Basic {base64 encoded string made of client_id:client_secret}'

--header 'Content-Type: application/x-www-form-urlencoded'

--data-urlencode 'grant_type=refresh_token'

--data-urlencode 'refresh_token={YOUR_REFRESH_TOKEN}'

--data-urlencode 'scope=boards:read'

If successful, the response you receive will contain a new access token with an expiration time and relevant scope information. Here’s an example:

{

    "access_token": "{an access token string prefixed with 'pina'}",

    "response_type": "refresh_token",

    "token_type": "bearer",

    "expires_in": 2592000,

    "scope": "boards:read"

}

Storing the access token to a JSON-encoded file (optional)

For example, you might store your token to common/oauth_tokens/access_token.json

{

"access_token": "string",

"name": "string",

"refresh_token": "string"

}

Using the access token

Include the access token in the request header as part of the key-value pair for authorization. The value for the key Authorization will be Bearer <your token>. For example, in curl, the header for a GET user_account request where the token was '123' would look like this:

curl https://api.redacted.com/v5/user_account --header 'Authorization: Bearer 123'

Additional Resources