Percolate enables third party applications to authenticate REST API requests utilizing the
OAuth 2.0 authorization code grant type per RFC 6749.
Because the Percolate API requires requests to be made on behalf of a specific user, the client credentials grant type is NOT supported at this time.
Note: OAuth2 credentials are associated with Percolate Accounts, which
own your Brand(s) and License(s). It is not possible to associate the
credentials with a Brand or a License.
Registering a client application
There is currently no online registration process, but an online form will be made available and ultimately registration will be self-serve on our developer portal (in progress).
In the interim, please email email@example.com with the following:
- Name of the app
- The name of the Percolate account for which the app is being developed
- The OAuth 2.0 redirection endpoint as defined by RFC 6749 (must utilize https). For security purposes, Percolate will only redirect authenticated users to the provided redirect URL.
- The email address of the Percolate user to be the Integration Manager. This user account will be capable of resetting your Client Secret using our API.
Once created, you will be provided with a Client ID, and instructions for using our API to reset your Client Secret. The Client Secret is a private value that MUST NOT be shared with anyone.
Obtaining a User Access Token
1. Redirect the User
To obtain an authorization code, the user’s browser must be redirected to Percolate’s authorization endpoint.
Once redirected, the user will be presented with the Percolate login form, requesting that authorization be granted to your application to access their account.
response_type: Value MUST be "code"
client_id: Your application client ID
state: An opaque value that will be included when the authorization server redirects the user-agent to your applications redirect URL. This should be used for cross-site request forgery protection (Note: this is not required per the OAuth2 spec, but is required by Percolate)
Once a user has been authenticated and granted access to your application, the user’s browser will be redirected to your client redirect URL with the following query parameters:
code: The OAuth 2.0 authorization code. Valid for 300 seconds from time of issuance
state: The original, unaltered value included in the original redirect
As described in the next section,
code is the value that will be exchanged for an OAuth 2.0 access token and is valid for three hundred (300) seconds.
2. Request an Access Token
Once your application receives the authorization code on your redirect endpoint, an access token request should be made to Percolate’s token endpoint (with said
Request/refresh a token
Pending Breaking Change - Token API
authorized_tenant_id will be added to the token API response. This will identify the
tenant whose data the access token allows to be accessed. This ID will
be derived from the user's choice of which tenant's data your integration may access.
Until this parameter is added to the response of the token API, you may assume that the
authorized_tenant_id is the ID of the tenant that owns the OAuth2 client.
This means that, when using OAuth2, you may only access your own Percolate tenant's data.
We are working to implement the feature whereby a user can choose to allow your integration
to access other tenant's data. When that work is completed, you may receive a token API
response that identifies a tenant other than your own. You may then use the returned access
token to access other tenant's data on that user's behalf.
Once these updates are put into effect, existing access tokens may be invalidated, requiring users to re-authorize existing client apps.
Making an Authenticated Request
The access token issued by Percolate, a bearer token type as defined in RFC 6750, can be used to make authenticated API requests on behalf of the corresponding user. To do so, include the
Authorization request header with the value found in your access token's
access_token property. For example:
Authorization: Bearer pBkgJV_cEVKESx4SH7wm-kYdfVgnyhDGCdqoRtygQE7
If an access token has become invalid, API requests will receive a "401 Unauthorized" response. A token maybe become invalid for the following reasons:
expires_at date/time has exceeded
- The user has revoked the grant
- A new access token has been issued for this user, invalidating the existing one
Note: As stated above, a token may only be used to access data from the tenant
identified in the
authorized_tenant_id of the token API response. Until we have
implemented that change, you may assume that the
authorized_tenant_id is the
ID of the tenant that owns the OAuth2 configuration.
Refreshing an Access Token
The token api may be used to refresh an access token
that meets all of the following conditions:
- The access token has not been disabled (which may happen either deliberately
by the user, or by some internal system event).
- The access token is either not expired or has not been expired for more than 14
In other words, if the access token has not been deliberately disabled by the user,
the refresh token may be used up to 14 days after the access token expires.
If the token does not meet those conditions, the user must repeat the 3-legged
OAuth2 flow to grant your application permission to retrieve an access token.