API docs by Redocly

Nodeblocks Auth-Service Default Adapter (1.0)

Download OpenAPI specification:Download

API document for nb-auth-service default adapter

API document for auth service default adapter. Include the following functions:

  • login (with MFA feature)
  • oauth2 logins use google/apple/line
  • validate token
  • invalidate token
  • restore token
  • generate onetime token Please be noted that based on the configuration of adapter (e.g. enableRefreshToken), some of the functions may not be available.

App

System Health Check

Get app status

Validations

  • This endpoint is public

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "packageInfo": {
    }
}

Auth

Login to System

Login use email and password.

  • In non-MFA mode, this endpoint will return accessToken and refreshToken
  • In MFA mode, this endpoint will return onetimeToken, for user to verify onetime-password
    • need to use with /auth/verify/otp endpoint to get the final accessToken and refreshToken

Validations

  • This endpoint have no authentication
  • This endpoint have no authorization
Request Body schema: application/json

request body to login

email
required
string <email> (email.field)
password
required
string (password.field) >= 8 characters
fingerprint
required
string (fingerprint.field)

Responses

Request samples

Content type
application/json
{
  • "email": "user@example-email.com",
  • "password": "password1",
  • "fingerprint": "xxxxxxxxxx"
}

Response samples

Content type
application/json
Example
{
  • "userId": "userId",
  • "accessToken": "token",
  • "refreshToken": "refreshToken"
}

Logout from system (only for cookie based authentication)

Logout from system (only for cookie based authentication). The logout endpoint will invalidate the session cookie, by setting the cookie's maxAge to 0.

If the authType of auth-service is not cookie, this endpoint will return 404.

path Parameters
userId
required
string^[0-9a-z]{24}$
Example: 0123456789ab0123456789ab

A unique identifier of an user.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Check Token's Validity and Return Information

Check if one token is validate token.

Client can check the token to obtain token information. For example, after login, check the token to obtain userId. After get one-time-token, check the token to verify it is valid or not.

If token is one-time-token, it will make it invalid after the check.

Validations

  • If the token is user accessToken, no validaion needed
  • If the token is onetimeToken, only app user (internal service) are allowed to do the check
  • If the token type is neither accessToken nor onetimeToken, it will return 403
Authorizations:
x-nb-fingerprintNone
Request Body schema: application/json

request body to check token

token
required
string (token.field)

nb-token(encrypted JWT token)

fingerprint
string (fingerprint.field)
target
string (target.field)

path

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "fingerprint": "string",
  • "target": "/"
}

Response samples

Content type
application/json
Example
null

Invalidate Onetime Token

Make one stateful token invalidate

Validations

  • valid Authorization token have been specified in the request header
  • Authorization token must be internal token
Authorizations:
bearerAuth
Request Body schema: application/json

request body to invalidate token

token
required
string (token.field)

nb-token(encrypted JWT token)

fingerprint
string (fingerprint.field)
target
string (target.field)

path

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "fingerprint": "string",
  • "target": "/"
}

Response samples

Content type
application/json
{
  • "token": "token"
}

Restore Token

Rollback the invalidate_token process. Make a stateful token invalidated by POST /invalidate_token endpoint valid.

Validations

  • valid Authorization token have been specified in the request header
  • Authorization token must be internal token
Authorizations:
bearerAuth
Request Body schema: application/json

request body to restore token

token
required
string (token.field)

nb-token(encrypted JWT token)

fingerprint
string (fingerprint.field)
target
string (target.field)

path

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "fingerprint": "string",
  • "target": "/"
}

Response samples

Content type
application/json
{
  • "token": "token"
}

Generate Onetime Token

Generate onetime stateful token. This token can be passed to user, for some authentication process.

For example, user can use this token to reset password, or to verify email.

Validations

  • valid Authorization token have been specified in the request header
  • Authorization token must be internal token
Authorizations:
bearerAuth
Request Body schema: application/json

request body to generate onetime token

fingerprint
string (fingerprint.field)
target
string (target.field)

path

data
object

custom data

Responses

Request samples

Content type
application/json
{
  • "fingerprint": "string",
  • "target": "/",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "token": "token"
}

Onetime Login to System

Login using onetime login.

  • Will return an access token and refresh token if enabled.
  • Will set cookies if cookies are enabled.

Validations

  • This endpoint have no authentication
  • This endpoint have no authorization
Request Body schema: application/json

request body for onetime login

onetimeToken
required
string (token.field)

nb-token(encrypted JWT token)

fingerprint
required
string (fingerprint.field)

Responses

Request samples

Content type
application/json
{
  • "onetimeToken": "onetime-token",
  • "fingerprint": "fingerprint"
}

Response samples

Content type
application/json
Example
{
  • "userId": "userId",
  • "accessToken": "token",
  • "refreshToken": "refreshToken"
}

Refresh Access Token

Generate a new access token using refreshToken.

Validations

  • fingerprint need to be specified in the request body
  • valid refreshToken need to be specified in the request body
  • fingerprint / refreshToken combination must be valid
Request Body schema: application/json

request body to generate new access token with refresh token

fingerprint
string (fingerprint.field)
refreshToken
string (token.field)

nb-token(encrypted JWT token)

Responses

Request samples

Content type
application/json
{
  • "fingerprint": "string",
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "token"
}

Delete refresh tokens for user

Delete the refresh token for user.

Validations

  • Authorization token must be internal token
Authorizations:
x-nb-fingerprintbearerAuth

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Check Onetime Code matches with Token or not

Check if onetime code is match with the one stored in onetime-token or not.

If code is a match, return user id, access token, and refresh token.

Validations

  • This endpoint have no authentication
  • This endpoint have no authorization
Request Body schema: application/json

request body to check code

token
required
string (token.field)

nb-token(encrypted JWT token)

code
required
string (code.field)

random digit genereated send to user

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "userId": "userId",
  • "accessToken": "token",
  • "refreshToken": "refreshToken"
}

Resend two factor code to user

Check onetime token and extract user info and invalidate the token.

Regenerate two factor code and send it to user.

Validations

  • valid Authorization token have been specified in the request header
Request Body schema: application/json

resend two factor code to user

token
required
Object (onetimeToken.field)

data encoded in onetime token. The format depends on what encoded in generate onetime token request.

Responses

Request samples

Content type
application/json
{
  • "token": { }
}

Response samples

Content type
application/json
{
  • "accessToken": { }
}

OAuth

Redirect to Google OAuth2 login page

Requesting this endpoint will redirect you to Google OAuth2 login page

query Parameters
fingerprint
string

fingerprint of client machine

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Google OAuth2 callback

Endpoint used for handling Google OAuth2 login callback.

Responses

Redirect to Apple OAuth2 login page (Not ready yet)

Requesting this endpoint will redirect you to Apple OAuth2 login page

query Parameters
fingerprint
string

fingerprint of client machine

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Apple OAuth2 callback (Not ready yet)

Endpoint used for handling Apple OAuth2 login callback.

Responses

Redirect to Line OAuth2 login page (Not ready yet)

Requesting this endpoint will redirect you to Line OAuth2 login page

query Parameters
fingerprint
string

fingerprint of client machine

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Line OAuth2 callback (Not ready yet)

Endpoint used for handling Line OAuth2 login callback.

Responses

Redirect to Twitter OAuth2 login page (Not ready yet)

Requesting this endpoint will redirect you to Twitter OAuth2 login page

query Parameters
fingerprint
string

fingerprint of client machine

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Twitter OAuth2 callback (Not ready yet)

Endpoint used for handling Twitter OAuth2 login callback.

Responses