{"_id":"59cccd03c185cb0010ebecd7","project":"551111444878730d00220ecb","initVersion":{"_id":"587395fe11b3ec1900d3b6db","version":"3"},"user":{"_id":"598434abf169ec0039573cf5","username":"","name":"Stavros Soleas"},"__v":0,"hidden":false,"createdAt":"2017-09-28T10:20:51.402Z","fullscreen":false,"htmlmode":false,"html":"","body":"Workable API endpoints can also be accessed 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.\n\n> Read more about [OAuth 2.0](https://tools.ietf.org/html/rfc6750)\n\n## Authorization Code Flow\nThe following scheme shows how a fresh start is made for a User that hasn't previously enabled the integration.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/7a06894-authorization_flow.png\",\n        \"authorization_flow.png\",\n        915,\n        645,\n        \"#0a0708\"\n      ]\n    }\n  ]\n}\n[/block]\n\nThe process consists of 4 steps\n1. 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:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/be275af-grant_permissions.png\",\n        \"grant_permissions.png\",\n        608,\n        545,\n        \"#ebf3f3\"\n      ]\n    }\n  ]\n}\n[/block]\n\n2. Workable then triggers a redirect to the Partner's `redirect_uri` providing an authorization code in the query params.\n3. 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.\n4. Use access token to access Workable. e.g. retrieve the candidates the User has access to.\n\n## Refresh Token\nThe 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.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/6c9c555-refresh_token_flow.png\",\n        \"refresh_token_flow.png\",\n        505,\n        325,\n        \"#0b0808\"\n      ]\n    }\n  ]\n}\n[/block]\n\nThe process uses the `refresh_token` to get a new `access_token` (the `refresh_token` is always provided alongside the `access_token`)\n\nSo only 2 steps for getting a new access token and accessing the Workable API\n1. Partner requests a new `access_token` using the `refresh_token`. The response contains a new pair of tokens.\n2. Partner uses new `access_token` to access Workable. e.g. retrieve the candidates the User has access to.\n\n## Revoke Permissions Flow\nThe 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`.\n\n> Remember if the `access_token` is expired, the `refresh_token` flow should be used before using the `revoke` permissions flow\n\n## Examples\n\n#### Authorization Code\n\n1. The flow should be triggered by popping a window to the User's browser redirecting him to:\n```https://www.workable/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&resource=user&response_type=code&scope=r_jobs+r_candidates+w_candidates```\nUsing 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).\n\n2. Workable will redirect to this endpoint and also will include an authorization code. The URL will look like: ```http://partner.com/redirect?code=e7fcd407a73dbe5219```.\n\n3. Get a new pair of `access_token` and `refresh_token` using a `POST`. The request should look like: \n\n```\nRequest:\ncurl -F grant_type=authorization_code \\\n     -F client_id={uid} \\\n     -F client_secret={secret} \\\n     -F code={authorization_code} \\\n     -F redirect_uri={redirect_uri} \\\n     -X POST https://www.workable.com/oauth/token\nResponse:\n{\n  \"access_token\":\"9a0cd4d51849d4a7eeb0111fc40174065b1892ee297e493ca2c8c5374f70be37\",\n  \"token_type\":\"bearer\",\n  \"expires_in\":7200,\n  \"refresh_token\":\"0d0c63f9faee831368f6d7e6fe057f9f88040eae244ef4f462e8751deeef5ca3\",\n  \"scope\":\"r_jobs\",\n  \"created_at\":1486567779\n}\n```\n\n#### Refresh Token\n\nUsing the refresh token, you can receive a new pair of `access_token` and `refresh_token` using a request like:\n\n```\nRequest:\ncurl -F grant_type=refresh_token \\\n     -F client_id={uid} \\\n     -F client_secret={secret} \\\n     -F refresh_token={refresh_token} \\\n     -X POST https://www.workable.com/oauth/token\nResponse:\n  {\n    \"access_token\":\"4320f5e8b75f12\",\n    \"token_type\":\"bearer\",\n    \"expires_in\":7200,\n    \"refresh_token\":\"3335068da9865\",\n    \"scope\":\"r_jobs r_candidates w_candidates\"\n  }\n```\n\n\n#### Revoke Permissions\n\nA request for revoking a User's grant, looks like:\n\n```\ncurl -H 'Authorization: Bearer {access_token} \\\n     -F 'token={refresh_token} \\\n     -X POST 'https://www.workable.com/oauth/revoke'\n```\n\n> 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\n\n#### Issuing a request against the Workable API\n\nWhen 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.\n\n1. Get the accounts\n```\n  curl -H 'Authorization: Bearer {access_token} 'https://www.workable.com/spi/v3/accounts'\n```\n\nGet more info on what you can do with the Workable [API](https://workable.readme.io)\n\n> [Apply to become a Workable partner](https://developers.workable.com/partner-program/apply)","slug":"oauth","title":"OAuth 2.0"}

OAuth 2.0


Workable API endpoints can also be accessed 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](https://tools.ietf.org/html/rfc6750) ## Authorization Code Flow The following scheme shows how a fresh start is made for a User that hasn't previously enabled the integration. [block:image] { "images": [ { "image": [ "https://files.readme.io/7a06894-authorization_flow.png", "authorization_flow.png", 915, 645, "#0a0708" ] } ] } [/block] 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: [block:image] { "images": [ { "image": [ "https://files.readme.io/be275af-grant_permissions.png", "grant_permissions.png", 608, 545, "#ebf3f3" ] } ] } [/block] 2. Workable then triggers a redirect to the Partner's `redirect_uri` providing an authorization code in the query params. 3. 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. 4. 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. [block:image] { "images": [ { "image": [ "https://files.readme.io/6c9c555-refresh_token_flow.png", "refresh_token_flow.png", 505, 325, "#0b0808" ] } ] } [/block] 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/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 -H 'Authorization: Bearer {access_token} \ -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](https://workable.readme.io) > [Apply to become a Workable partner](https://developers.workable.com/partner-program/apply)