Generating/revoking access tokens for Workable's API

Workable provides an API that gives you complete control over your data. You can access, manage, and extract recruiting data from your Workable account by generating API access tokens.

To generate or revoke access tokens for your account, you must be an Admin user in Workable; there is no dedicated access only for this use. As an Admin user, you can:

• create tokens with expiration
• choose the scopes for the tokens you wish to create
• have multiple account-level tokens with different scopes, different expirations, etc.

Once one or more access tokens are created, you should share them with the relevant parties (developers, IT team). 

 

Generate a new token

As an Admin user:

1. Click your profile icon in the upper right and navigate to Settings > Integrations > Apps
2. Locate the API Access Tokens section near the top of the page
3. Click the button + Generate API token
   
   
4. Add a name for your token, e.g., if it is used to access candidate data, you can name it "Candidates"
5. Select the token's expiration from the dropdown; available options will be: 30 days, 90 days, 6 months, 1 year, 2 years
6. Select which scope(s) will be enabled for this token; you must select at least one scope
7. Click Generate token to complete the process
   
8. Once your access token is generated, you will see a modal with the full token (a long string of random letters and numbers). Click to copy it to your clipboard. 

 

Supported API scopes

API tokens can be configured to enable different scopes while making calls. The set of scopes of a token makes it usable in specific (or all) the SPI endpoints.

The supported scopes are:

API scope	SPI endpoints access
r_account	Access configuration information about your account via: /departments, /legal_entities, /work_schedules, /employee_fields
r_candidates	Access your candidates via: /jobs/:shortcode/activities, /candidates, /candidates/:id, /candidates/:id/activities, /candidates/:id/offer
r_employees	❗This scope gives access to sensitive employee information via: /employees, /employees/:id, /employees/:id/documents
r_jobs	Access your jobs via: /jobs, /jobs/:shortcode, /jobs/:shortcode/application_form, /jobs/:shortcode/questions, /jobs/:shortcode/stages, /jobs/:shortcode/custom_attributes, /jobs/:shortcode/members, /jobs/:shortcode/recruiters, /custom_attributes, /events, /events/:id Via this scope, you will also have access to the below endpoints: /accounts, /accounts/:subdomain, /members, /recruiters, /stages, /candidates/:id/update_custom_attribute_value
r_requisitions	Access your requisitions via: /requisitions, /requisitions/:code
r_timeoff	Access your time-off data via: /timeoffcategories, /timeoffrequests, /timeoffbalances
w_candidates	Change your candidates via: /candidates, /talent_pool/candidates, /candidates/:id/comments, /candidates/:id/tags, /candidates/:id/disqualify, /candidates/:id/revert, /candidates/:id/copy, /candidates/:id/relocate, /candidates/:id/move, /candidates/:id/ratings
w_comments	Add comments to your candidates via: /candidates/:id/comments (also included in the w_candidates scope)
w_employees	Change your employees via: /employees, /employees/:id, /employees/:id/documents
w_timeoff	Create new time-off requests via: /timeoffrequests

 

Revoke tokens

On the same page, Admin users have the ability to revoke individual tokens. Revoking a token means that every script or application that accesses the Workable SPI through this token will stop functioning. You must generate a new access token and update it in every script or application previously bound to the old one.

1. Click the three dots menu next to the token you need to revoke and then Revoke token
2. Click Revoke to confirm the action

 

Renew an expired token

When a token expires, you can quickly renew it by clicking the Renew button under it. Renewing a token means it won't change, so all scripts or applications using this token will continue functioning normally.

 

Useful documentation