# User Access Token Whisk supports OAuth 2.0 flow for generating user access token to authorize API requests. OAuth 2.0 is a specification outlined in [RFC 6749](https://tools.ietf.org/html/rfc6749) that allows third-party services to make requests on behalf of a user without accessing the passwords and other sensitive information. You can get familiar with OAuth 2.0 using [Aaron Parecki’s "OAuth 2 Simplified" guide](https://aaronparecki.com/2012/07/29/2/oauth2-simplified). ## Code Grant The authorization code grant is used when an application exchanges an authorization code for an access token. After the user returns to the application via the redirect URL, the application will get the authorization code from the URL and use it to request an access token. ### Step 1: User Authorization First, the user has to grant you app permission to access their data or do actions on their behalf. Whisk provides an authorization page where users can securely sign in using their Whisk credentials or third-party accounts like Google, Facebook, etc. to grant permissions. This authorization page is accessed using the authorization URL. | **Authorization URL** | `https://login.whisk.com/oauth/v2/authorize` | | --------------------- | -------------------------------------------- | To ensure that the driver grants permissions properly, you must append the query parameters to the authorization URL as described below. ```http https://login.whisk.com/oauth/v2/authorize?scope=&client_id=&response_type=code&redirect_uri= ``` | Parameter | Description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `scope` |

This parameter indicates the parts of the user's data that you wish to access. You can also request multiple scopes separated by space or comma.

To see the full list of supported scopes, read Authentication Scopes.

| | `client_id` | The client ID of your application. | | `response_type` | OAuth 2.0 response type. The only option supported at the moment is `code`. | | `redirect_uri` | The URL to redirect the resource owner to after authorization. | | `state` (optional) | An arbitrary string value that will be passed back to your redirect URI. This parameter should be used to protect against cross-site request forgery (CSRF) | | `identity_provider` (optional) | If provided, the authorization process is immediately forwarded to the specified identity provider (e.g. Google, Facebook) | After you’ve supplied the needed parameters, present this authorization URL as a link for the user to visit. ### Step 2: Receive redirect Once the Whisk user authenticates and authorizes your app, Whisk will issue an HTTP 302 redirect to the `redirect_uri` passed in [Step 1](#step-1-user-authorization). On that redirect, you will receive a single-use authorization code that expires in 1 day. ```bash GET https://your-redirect-uri/?code= ``` This is the authorization code you need for the next step. {% hint style="info" %} In order for the redirect to work correctly, Whisk must approve the URL. For this, you must contact support in the dashboard. {% endhint %} ### Step 3: Get an access token Use the **Token Exchange URL** to exchange the authorization code for an `access_token` which will allow you to make requests on behalf of the user. | **Exchange Token URL** | `https://login.whisk.com/oauth/v2/token` | | ---------------------- | ---------------------------------------- | **Example Request**: ```bash curl "https://login.whisk.com/oauth/v2/token" \ -F "client_id=" \ -F "client_secret=" \ -F "grant_type=authorization_code" \ -F "redirect_uri=" \ -F "code=" ``` | Parameter | Description | | --------------- | ----------------------------------------------------------------------------------------------- | | `client_id` | The Client ID of your application. | | `client_secret` | The Client Secret of your application. | | `grant_type` | This should be set to `authorization_code`. | | `redirect_uri` | The base of the URI must match the `redirect_uri` used in [Step 1](#step-1-user-authorization). | | `code` | The authorization code from [Step 2](#step-2-receive-redirect). | **Example Response:** ```javascript { "access_token": "Xb609ErrcoRNwll9wwxbk70OxFrbxEOu8Ui8ZzV4yJDA9RvLRGFhlMAAfkP2OmSS", "token_type": "Bearer", "expires_in": 2592000, "scope": [ "cookbook:write" ], "refresh_token": "oS1437tty6buHTef0VGkXgcR7PvOt2DDUntSjWaCtDqJX8osK7d3Mip38NjpJdTH" } ``` The `access_token` is valid for the time described by `expires_in` (in seconds). The `refresh_token` expires after one year and can be used to obtain a new `access_token` at any time given provided your application is still authorized to access the API on behalf of this user. The scope in the token response indicates what access was actually granted by user. {% hint style="info" %} The `access_token` retrieved from authenticating a user account stays active even when a user changes the account password or other account details. {% endhint %} ### Refreshing Tokens If you requested the access token with the `offline_access`scope, the response will include a `refresh_token`which can be used to refresh the access token. When the user’s `access_token`has expired, you can obtain a new `access_token`by exchanging the `refresh_token`associated with the `access_token`using the Token Exchange URL. Refreshing the user access token means that you don’t need to ask the user to authorize your app for the same permissions again (`offline_access`). ```bash curl "https://login.whisk.com/oauth/v2/token" \ -d "client_id=" \ -d "client_secret=" \ -d "grant_type=refresh_token" \ -d "refresh_token=" ``` {% hint style="info" %} A `refresh_token`is valid for one year and tokens that have been inactive for more than one year will be invalidated. {% endhint %} ## Implicit Grant {% hint style="warning" %} Implicit flow is the less secure approach. We recommend you to consider [Code Grant](#code-grant) flow instead. {% endhint %} First, the user has to grant your app permission to access their data or do actions on their behalf. Whisk provides an authorization page where users can securely sign in with their Whisk username and password or accounts from other providers (Google, Facebook, etc.) to grant permissions. This authorization page is accessed through the authorization URL. To ensure that the driver grants permissions to your app properly, supply query parameters to that URL as described below. ```http https://login.whisk.com/oauth/v2/authorize?client_id=&response_type=token&redirect_uri= ``` | Parameter | Description | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | `response_type` | OAuth 2.0 response type. token | | `client_id` | The client ID of your application. | | `redirect_uri` | The URI we will redirect back to after authorization by the resource owner. | | `state`(optional) | State which will be passed back to you to prevent tampering. | | `identity_provider` (optional) | If provided, the authorization process is immediately forwarded to the specified identity provider (e.g. Google, Facebook) | After you’ve supplied the needed parameters, present this authorization URL as a link for the user to visit. Unlike the authorization code grant type, in which the client makes separate requests for authorization and for an access token, the client receives the access token as the result of the authorization request. Once the Whisk user authenticates and authorizes your app, Whisk will issues an access token and delivers it by adding the following parameters to the fragment component of the redirection URI using the `application/x-www-form-urlencoded` format **Example Response**: ```http http://example.com/#access_token=Xb609ErrcoRNwll9wwxbk70OxFrbxEOu8Ui8ZzV4yJDA9RvLRGFhlMAAfkP2OmSS&state=xyz&token_type=Bearer&expires_in=86400 ``` The `access_token`is valid for the time described by `expires_in`(in seconds). The `refresh_token`does not return. {% hint style="info" %} The `access_token`retrieved from authenticating a user account will stay active even when a user changes the account password or other account details. {% endhint %} ## Use bearer token You can pass the `access_token` returned in the previous steps as a bearer token in the Authorization header, or pass it in as a query parameter in the URL. Here is how you pass it in a header: ```bash curl "https://api.whisk.com/v2/me" \ -H "Authorization: Bearer " ```