User Access Token

The Whisk Graph API uses OAuth 2.0 to allow developers to get a user access token to access a single user’s data or do actions on their behalf. OAuth 2.0 is a specification outlined in RFC 6749 that allows third-party services to make requests on behalf of a user without accessing passwords and other sensitive information. If you are unfamiliar with OAuth 2.0, check out Aaron Parecki’s “OAuth 2 Simplified” guide.

OAuth 2.0 Endpoints

Authorization Hosthttps://login.whisk.com
Authorization Endpointhttps://login.whisk.com/oauth/v2/authorize
Token Exchange Endpointhttps://login.whisk.com/oauth/v2/token

Authorization Code Grant

Step 1: User Authorization

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.

https://login.whisk.com/oauth/v2/authorize?client_id=<CLIENT_ID>&response_type=code&redirect_uri=<REDIRECT_URI>
ParameterDescription
response_typeOAuth 2.0 response type. code
client_idThe client ID of your application.
redirect_uriThe URI we will redirect back to after an authorization by the resource owner.
state (optional)State which will be passed back to you to prevent tampering.
identity_provider (optional)If provided, authorization process is immediately forwarded to 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. On that redirect, you will receive a single-use authorization code which expires in 10 minutes.

GET https://your-redirect-uri/?code=<AUTHORIZATION_CODE>

Note the code query param above, this is the authorization code you need for the next step.

Step 3: Get an access token

Use the Token Exchange endpoint to exchange the authorization code for an access_token which will allow you to make requests on behalf of the user.

Example Request:

curl "https://login.whisk.com/oauth/v2/token" \ -F "client_id=<CLIENT_ID>" \ -F "client_secret=<CLIENT_SECRET>" \ -F "grant_type=authorization_code" \ -F "redirect_uri=<REDIRECT_URI>" \ -F "code=<AUTHORIZATION_CODE_FROM_STEP_2>"
ParameterDescription
client_idThe Client ID of your application.
client_secretThe Client Secret of your application.
grant_typeIn this step, this should be set to authorization_code
redirect_uriThe base of the URI must match the redirect_uri used during Step 1 above.
codeThe authorization code from Step 2: Receive Redirect.

Example Response:

{ "access_token": "Xb609ErrcoRNwll9wwxbk70OxFrbxEOu8Ui8ZzV4yJDA9RvLRGFhlMAAfkP2OmSS", "token_type": "Bearer", "expires_in": 2592000, "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 that your application is still authorized to access the API on behalf of this user.

The access_token retrieved from authenticating a user account will stay active even when a user changes the account password or other account details.

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 endpoint. 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).

curl "https://login.whisk.com/oauth/v2/token" \ -F "client_id=<CLIENT_ID>" \ -F "client_secret=<CLIENT_SECRET>" \ -F "grant_type=refresh_token" \ -F "refresh_token=<REFRESH_TOKEN>"
A refresh_token is valid for one year and tokens that have been inactive for more than one year will be invalidated.

Implicit Grant

Implicit flow is the less secure approach. Please consider Code Grant flow instead.

Step 1: User Authorization

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.

https://login.whisk.com/oauth/v2/authorize?client_id=<CLIENT_ID>&response_type=token&redirect_uri=<REDIRECT_URI>
ParameterDescription
response_typeOAuth 2.0 response type. token
client_idThe client ID of your application.
redirect_uriThe URI we will redirect back to after an authorization by the resource owner.
state (optional)State which will be passed back to you to prevent tampering.
identity_provider (optional)If provided, authorization process is immediately forwarded to 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://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.

The access_token retrieved from authenticating a user account will stay active even when a user changes the account password or other account details.

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.

Example: OAuth token sent in a header

curl "https://graph.whisk.com/v1beta/me" \ -H "Authorization: Bearer <Access-Token>"