Grindery Nexus Authentication Process

Last updated by Jamiu Idowu 3 months ago

This documentation describes the Grindery Nexus API authentication flow and it is primarily for developers who work on apps that use Nexus platform.

Getting Started

A developer needs authentication to use the Nexus API (read/edit/create/delete workflows, etc): https://github.com/grindery-io/grindery-nexus-client/blob/master/DOCUMENTATION.md

The authentication flow is compliant with OAuth2 standard and requires users to sign an authentication message using their metamask wallets. In a nutshell, the Grindery Nexus Authentication flow is as follows:

Web client gets user wallet address using metamask.

Web client sends user wallet address to the Nexus auth server, and receives a challenge message.

User signs the message using the metamask extension.

Web client compiles challenge message and signature into a “code” string, and sends to Nexus auth server.

Nexus auth server returns access token that can be used to access the Nexus API.

Auth URLs

get challenge message

URL: https://orchestrator.grindery.org/oauth/session

Method: GET

Query props:

address - EVM wallet address of the user

Response props:

message - string, that should be signed by user using MetaMask

get access token

URL: https://orchestrator.grindery.org/oauth/token

Method: POST

Body props:

grant_type - ‘authorization_code’

code - base64 encoded JSON string containing auth message and signature {"message":"xxx", "signature": "xxx"}

Response props:

access_token

refresh_token

expires_in

token_type

register auth session

URL: https://orchestrator.grindery.org/oauth/session-register

Method: POST

Body props:

refresh_token - Optional. If set will set a long term httpOnly authentication cookie. If not set will clear the cookie.

refresh access token

URL: https://orchestrator.grindery.org/oauth/token

Method: POST

Body props:

grant_type - ‘refresh_token’

refresh_token - refresh_token returned in the access token request.

Response props:

access_token

expires_in

token_type

Simplifying Development

To simply development, Grindery provides you with an authentication page and a React hook. They are as follows:

Authentication page

A page for user authentication where challenge message fetching and metamask signing is already implemented. The page can be used as an entry point, to get the user's authentication “code” containing a signed challenge message. The “code” can then be exchanged to the “access_token”.

Page url: https://orchestrator.grindery.org/oauth/authorize

Required query params:

redirect_uri

response_type = “code”

Check out an example here .

Once authenticated, a user will be redirected to the “redirect_uri”. The “code” string that can be exchanged to access_token will be added as a query param to the redirect url.

Example: https://example.com?code=xxxxxxxxx…

React hook

A reusable ReactJS component that handles user authentication state in React app.
Github: https://github.com/grindery-io/use-grindery-nexus
NPM: https://www.npmjs.com/package/use-grindery-nexus

The hook takes care of the authentication flow and provides:

“connect” method, to initiate auth process.

“disconnect” method, to stop user session.

“user” property that contains user ID

“token” object that contains access token, refresh token (basically it contains the response of “get access token endpoint”)

“address” property that contains user’s wallet address