Grindery OAuth 2.0
This documentation describes the Grindery OAuth 2.0 authentication flow and it is primarily for developers who work on apps that use Grindery platform.
Getting Started
A developer needs authentication to use the Grindery API (get user information, read/edit/create/delete workflows and workspaces, etc).
The authentication flow is compliant with OAuth 2.0 standard and requires users to sign an authentication message using their metamask wallets. In a nutshell, the Grindery OAuth flow is as follows:
The OAuth flow
Step 1: Sending users to the sign-in page
Required parameters:
The following values should be passed as GET parameters:
Param | Description |
response_type | Must be `code` |
redirect_uri | The full URL (including protocol) of your application’s authentication page. |
Response parameters
If the user authorizes your app, Grindery will redirect back to your specified ` redirect_uri` with a temporary authentication code in a ` code` GET parameter.
Param | Description |
code | Authentication code |
Step 2: Exchanging an authentication code for an access token
If all is well, exchange the authorization code for an access token by sending a POST request to https://orchestrator.grindery.org/oauth/token .
Required parameters:
The following values should be passed as body parameters:
Param | Description |
code | Authentication code your application received on the previous step. |
grant_type | Must be `authorization_code`. |
Response parameters
If authentication code is valid, you will get these values in response:
Param | Description |
access_token | User’s access token |
refresh_token | User’s refresh token |
expires_in | The time for which access token will be valid |
token_type | Access token type |
Step 3: Using access tokens
All requests to Grindery API must be authenticated. The best way to communicate your access tokens, also known as bearer tokens, is by presenting them in a request's Authorization HTTP header:
Authorization: Bearer paste-user-access-token-here
Alternatively you can use JS client library to make requests to the API: https://github.com/grindery-io/grindery-nexus-client
To authenticate user with JS client, use `authenticate` method, and pass `access_token`.
Here is library full documentation: https://github.com/grindery-io/grindery-nexus-client/blob/master/DOCUMENTATION.md
Step 4: Refreshing access tokens
If the user's access token has expired, your application will need to use a refresh token, to get a new access token.
You can refresh the token by sending a POST request to https://orchestrator.grindery.org/oauth/token .
Required parameters:
The following values should be passed as body parameters:
Param | Description |
refresh_token | `refresh_token` returned in the access token request. |
grant_type | Must be `refresh_token`. |
Response parameters
If refresh token is valid, you will get these values in response:
Param | Description |
access_token | User’s access token |
expires_in | The time for which access token will be valid |
token_type | Access token type |