1. Wave • Developer Portal
  2. Documentation
  3. Create an App

OAuth Guide

Create an App

OAuth 2 is a protocol that lets your application request authorization to private data in a user’s Wave account without getting their password.

To proceed, you will first need to register an application. Your application is assigned a unique Client ID and Client Secret which will be used in the OAuth flow.

OAuth Flow

The flow to authorize users for your application is:

  1. Users are redirected to Wave to request authorization of connection
  2. Users are redirected back to your site by Wave
  3. Your application uses the user's access token to access the Wave API

1. Redirect to Wave to request authorization

Your application should redirect users to the following URL:
https://api.waveapps.com/oauth2/authorize/

GET Parameters

Name Required Description
client_id True The client id of the application you registered.
response_type True Use value code. This indicates that your server expects to receive an authorization code.
scope True A space-delimited list of scope values indicating which parts of the user's account you wish to access.
redirect_uri False The URI to return the user to after authorization is complete. If not provided, Wave will redirect users to the first redirect URI configured in the application's settings. See details below about Redirect URIs.
state False A random string generated by your application, which you'll verify later. Used to protect against cross-site request forgery attacks.
approval_prompt False Users might be prompted for the same authorization multiple times: sometimes this is acceptable or even desirable but other times it isn’t. Possible values are:
  • Use value auto so users are prompted only the first time. This is the default behaviour. Subsequent authorizations for the same application and scopes while there remains valid access token(s) will be automatically accepted. If the token is restricted to a single business, you also need to provide businessId parameter to indicate which business to reconnect.
  • Use value force so users are always prompted for authorization.
businessId False In the case where tokens are restricted to a single business (when a user is shown a drop down of business choices), the id of the business that you are recommending the user auth against.

2. User redirected back to your site by Wave

If the user authorizes your application, Wave redirects the user back to the specified redirect_uri with some additional GET parameters:

  • code - The server returns the authorization code in the query string. May only be exchanged once and expire 10 minutes after issuance.
  • state - The server returns the same state value that you passed (if you provided one). If the states don't match, the request may have been created by a third party and you should abort the process.

https://your-site.com/callback?code=AUTH_CODE_HERE&state=abc123

Exchange auth code for tokens

Your application should POST to: https://api.waveapps.com/oauth2/token/

POST Parameters

Content-Type: application/x-www-form-urlencoded

Name Required Description
client_id True The client id of the application you registered.
client_secret True The client secret of the application you registered.
code True The code you received as a response to Step 1.
grant_type True Use value authorization_code.
redirect_uri True Must match the originally submitted URI where the user was sent to after authorization was complete.

JSON Response

Content-Type: application/json

Name Type Description
access_token string The credential used in an HTTP Authorization header to access Wave's API.
expires_in integer Number of seconds an access token remains valid.
token_type string Indicates that access_token is a Bearer token.
scope string A space-delimited list of scope values stating which parts of the user's account you are allowed to access their behalf.
refresh_token string A long-lived token that is used to obtain a new access token after a previous one has expired.
userId string Wave User id that the tokens are for.
businessId string Wave Business id that the tokens are for. Only returned if tokens are restricted to a single business.

3. Using access tokens

The access token allows you to make requests to the API on behalf of a user.

See Clients to understand how to interact with the Wave's GraphQL API: https://gql.waveapps.com/graphql/public

curl -X POST "https://gql.waveapps.com/graphql/public" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "query { user { id defaultEmail } }", "variables": {} }'

Expired tokens and refreshing

An access token will expire in the time defined by expires_in (from response of Step 2).

If a token has expired you will need to refresh it using the refresh_token (from Step 2) to generate a new access_token. Once this is done, the previous access_token is invalidated.

Your application should POST to: https://api.waveapps.com/oauth2/token/

POST Parameters

Content-Type: application/x-www-form-urlencoded

Name Required Description
client_id True The client id of the application you registered.
client_secret True The client secret of the application you registered.
refresh_token True The refresh_token you received previously.
grant_type True Use value refresh_token.
redirect_uri True Must match the originally submitted URI where the user was sent to after authorization was complete.
scope False A subset of scopes from Step 1 can be provided. If not provided it defaults to the scopes from Step 1.

JSON Response

Response includes a new access_token in the same format from Step 2.

Redirect URIs

The redirect URI’s host and port must exactly match one of the whitelisted redirect entries in the application’s settings. The redirect URI’s path must reference a subdirectory of the application’s redirect URI.

Example with settings whitelisted redirect URI: http://your-site.com/callback

  • Accepted
    • https://your-site.com/callback
    • http://your-site.com/callback/wave/authorize
  • Invalid
    • http://your-site.com/foobar
    • http://your-site.com
    • http://your-site.com:8080
    • http://oauth.your-site.com
    • http://your-site.org

Multiple Authorizations

Your application may send a user through the OAuth flow multiple times.

You may use this behaviour to get access to a different business, get another token as needed, and upgrade an access token's OAuth scopes.

To send the user through the Authorize flow again, use GET parameter approval_prompt with value force so users are always prompted for authorization.

Revoking Tokens

Your application should POST to: https://api.waveapps.com/oauth2/token-revoke/

POST Parameters

Content-Type: application/x-www-form-urlencoded

Name Required Description
client_id True The client id of the application performing action.
client_secret True The client secret of the application performing action.
token True Access or refresh token being invalidated.
Updated: