Grindery Nexus Authentication Process 

Last updated by Jamiu Idowu 16 days 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 a 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 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 

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 

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 

Method: POST 
Body props: 
refresh_token - Optional. If set will set a long term httpOnly authentication cookie. If not set will clear the cookie. 

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 metamask signing is already implemented 
 
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. 

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  
Refreshed On: Sep 23, 2022 13:21:18 UTC+00:00