Grindery OAuth 2.0 

Last updated by Egor Milyukov 2 days ago
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: 
Application redirects users to the sign-in page. 
The user signs-in using MetaMask wallet (extension). 
The user gets redirected back to the application. 
Application exchanges authentication code to the access token. 
Application uses access token to get user information and make requests to the Grindery API. 

The OAuth flow 

Step 1: Sending users to the sign-in page 

Your application should redirect users to the following URL: https://flow.grindery.org/sign-in . 

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`. 

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

 
Refreshed On: Jan 26, 2023 20:06:57 UTC+00:00