Percolate enables third party applications to authenticate REST API requests
using either of two grant types: 1) the
OAuth 2.0 authorization code, or
2) client credentials per RFC 6749.
Your application can support either of these two grant types, but not both.
Note: OAuth2 credentials are associated with Percolate Accounts, which
are associated with your Tenant and License tree. It is not possible to
associate credentials directly with a Tenant or a License.
Registering a client application
Only a system admin or an integration client manager can register a new client
application. Additionally, this user must have two-factor authentication
enabled in Percolate.
Click here to enable
The system admin or manager can
click here to register
a new client application. When registering your application with Percolate, you
will decide which grant type to use: the
OAuth 2.0 authorization code, or the client
Once a new application is registered, we will provide you with a Client ID and a
Client Secret. The Client ID will be displayed at the top of the screen,
underneath the name of your application. To see the Client Secret, click the
"Show Secret" button, and enter your two-factor authentication code. You will
then be shown the Client Secret. Be sure to keep your Client Secret secure! It is
a private value for your application only, and it MUST NOT
be shared with anyone.
If you need to reset the Client Secret, you can do so by selecting the "Reset
Secret" button and entering your two-factor authentication code.
Obtaining an Access Token
Authentication Code Grant (3-Legged Flow)
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 application's 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.)
2. Authorization Response:
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
code: The OAuth 2.0 authorization code. Valid for 300 seconds from time of
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.
3. 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
Auth Code Grant
Client Credentials Grant (2-Legged Flow)
Request an Access Token
To obtain an access token for a client credentials grant, your application must
request an access token from Percolate's token endpoint.
Client Credentials Grant
Deprecated - API Token
authorized_tenant_id will be added to the token API response. This will identify the
tenant whose data the access token allows Percolate to access. 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 another 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 the 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.
Note that client credentials grant tokens do not need to be refreshed, as the
application can simply request a fresh token.