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

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