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):  
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 

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: 

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. 

refresh access token 

Method: POST 
Body props: 
grant_type - ‘refresh_token’ 
refresh_token - refresh_token returned in the access token request. 
Response props: 

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”. 
Required query params: 
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.
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: Jan 27, 2023 18:15:01 UTC+00:00