OAuth 2.0

Official partners can access Workable API endpoints through OAuth 2.0, utilizing the Authorization code flow. In this scenario the Partner should be authorized beforehand by Workable and get a client_id and client_secret which he should use for onboarding users.

Read more about OAuth 2.0

Authorization Code Flow

The following scheme shows how a fresh start is made for a User that hasn't previously enabled the integration.

915

The process consists of 4 steps

  1. The partner redirects the User to a Workable page. The user reviews the permissions and proceeds with granting access to his Workable account. A user would see a screen like this one:
608
  1. Workable then triggers a redirect to the Partner's redirect_uri providing an authorization code in the query params.
  2. The Partner exchanges this authorization code for an actual token which he can later use for accessing Workable API at the behest of the User.
  3. Use access token to access Workable. e.g. retrieve the candidates the User has access to.

Refresh Token

The access token is not permanent though. It has a TTL (Time To Live) value and after this time has passed a new access token should be created and retrieved. Refreshing a token doesn't need the User to grant permissions for a second time, since this action was explicitly carried in the 1st step. The following diagram shows how this can be done.

505

The process uses the refresh_token to get a new access_token (the refresh_token is always provided alongside the access_token)

So only 2 steps for getting a new access token and accessing the Workable API

  1. Partner requests a new access_token using the refresh_token. The response contains a new pair of tokens.
  2. Partner uses new access_token to access Workable. e.g. retrieve the candidates the User has access to.

Revoke Permissions Flow

The last step would be the case of User wishing to revoke permissions of accessing his account and it's a simple request to the /revoke endpoint including the User's access_token.

Remember if the access_token is expired, the refresh_token flow should be used before using the revoke permissions flow

Examples

Authorization Code

  1. The flow should be triggered by popping a window to the User's browser redirecting him to:
    https://www.workable.com/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&resource=user&response_type=code&scope=r_jobs+r_candidates+w_candidates
    Using the client_id provided to the partner by Workable and the redirect_uri (should also be the same provided by the partner in the provisioning process).

  2. Workable will redirect to this endpoint and also will include an authorization code. The URL will look like: http://partner.com/redirect?code=e7fcd407a73dbe5219.

  3. Get a new pair of access_token and refresh_token using a POST. The request should look like: 

Request:
curl -F grant_type=authorization_code \
     -F client_id={uid} \
     -F client_secret={secret} \
     -F code={authorization_code} \
     -F redirect_uri={redirect_uri} \
     -X POST https://www.workable.com/oauth/token
Response:
{
  "access_token":"9a0cd4d51849d4a7eeb0111fc40174065b1892ee297e493ca2c8c5374f70be37",
  "token_type":"bearer",
  "expires_in":7200,
  "refresh_token":"0d0c63f9faee831368f6d7e6fe057f9f88040eae244ef4f462e8751deeef5ca3",
  "scope":"r_jobs",
  "created_at":1486567779
}

Refresh Token

Using the refresh token, you can receive a new pair of access_token and refresh_token using a request like:

Request:
curl -F grant_type=refresh_token \
     -F client_id={uid} \
     -F client_secret={secret} \
     -F refresh_token={refresh_token} \
     -X POST https://www.workable.com/oauth/token
Response:
  {
    "access_token":"4320f5e8b75f12",
    "token_type":"bearer",
    "expires_in":7200,
    "refresh_token":"3335068da9865",
    "scope":"r_jobs r_candidates w_candidates"
  }

Revoke Permissions

A request for revoking a User's grant, looks like:

curl -F client_id={uid} \
     -F client_secret={secret} \
     -F token={refresh_token} \
     -X POST 'https://www.workable.com/oauth/revoke'

If a user revokes permissions either from Workable or from partner, the authorization code flow should be repeated. This case could manifest as a 401 response code on a refresh token request

Issuing a request against the Workable API

When the Partner has a valid access_token he can then issue requests towards Workable. In this example the Partner gets a list of the User's accounts. The access_token is included in the Authorization header.

  1. Get the accounts
  curl -H 'Authorization: Bearer {access_token} 'https://www.workable.com/spi/v3/accounts'

Get more info on what you can do with the Workable API

Apply to become a Workable partner