Auth & OAuth

Initialize authentication handoff between customer application and a BlueNexus application

post

Initialize a secure user authentication handoff to redirect an authenticated user from a customer application to a BlueNexus application without re-authentication. This endpoint returns a short-lived handoff code to include when redirecting the user to the BlueNexus application.

Access restriction: Whitelabel customer client only

Authorizations

access-token

AuthorizationstringRequired

Enter JWT access token

Body

application/json

Request body for initializing authentication handoff

redirectUristringRequired

The redirect URI to send the user back to

Example: https://example.com/callback

intentstring · enumRequired

The intent of the authentication request

Example: connectionsPossible values:

Responses

200

Authentication handoff initialized successfully

application/json

412

Unable to determine client criterias for secure handoff

500

Internal server error

application/json

post

/api/v1/auth/handoff/init

HTTPcURLJavaScriptPython

POST /api/v1/auth/handoff/init HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 69

{
  "redirectUri": "https://example.com/callback",
  "intent": "connections"
}

{
  "code": "a1b2c3d4e5f6g7h8i9j0",
  "expiresAt": "2024-12-31T23:59:59.000Z"
}

Authenticate user

post

Authenticate a user using a signed SIWE payload and an optional sessionId to continue an existing session. Returns access and refresh tokens as well as the session ID. The session ID can be stored for future authentication requests to continue on the same session.

Confidential clients must pass their credentials using Basic Auth in the Authorization header. Public clients without secret must pass the client_id in the body.

Access restriction: Whitelabel customer client only

Authorizations

basic-client

AuthorizationstringRequired

OAuth Client credentials

Header parameters

AuthorizationstringOptional

Basic auth credentials with client ID and secret. Optional, public clients without secret must pass the client_id in the body.

Body

application/json

Authenticate request body

client_idstringOptional

Client ID to pass for public clients (no secret). Clients with a secret can use the Basic authorization headers instead (recommended).

client_secretstringOptional

Client secret. Optional for public clients (no secret). Required for confidential clients. Clients with a secret can use the Basic authorization headers instead (recommended).

signaturestringRequired

Signature of the SIWE payload

session_idstringOptional

Session id to continue, if not provided a new session is created

Responses

200

Authenticate response

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

post

/api/v1/auth/authenticate

HTTPcURLJavaScriptPython

POST /api/v1/auth/authenticate HTTP/1.1
Host: 
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 405

{
  "client_id": "text",
  "client_secret": "text",
  "payload": {
    "domain": "example.com",
    "address": "0x1234...abcd",
    "statement": "text",
    "uri": "https://example.com/login",
    "version": "1",
    "chain_id": "1",
    "nonce": "b2xkLXN0YW1wLW5vbmNl",
    "issued_at": "2023-10-05T14:48:00.000Z",
    "expiration_time": "2023-10-05T15:48:00.000Z",
    "invalid_before": "2023-10-05T14:58:00.000Z",
    "resources": [
      "text"
    ]
  },
  "signature": "text",
  "session_id": "text"
}

{
  "session_id": "text",
  "token_type": "Bearer",
  "access_token": "text",
  "expires_in": 1,
  "refresh_token": "text",
  "refresh_expires_in": 1,
  "scope": "text"
}

OAuth token exchange

post

Either exchange an authorization code for an access token or refresh an access token using a refresh token.

Authorizations

client-authbasic-client

Header parameters

AuthorizationstringOptional

Basic auth credentials with client id and secret. If undefined, falls back to client id and secret in the body. Whatever the method, the client ID is required. Client without secret should use the body.

Body

application/json

Token exchange request body

grant_typestring · enumRequired

OAuth grant type

Possible values:

codestringOptional

Authorization code. Required for the authorization_code grant type.

redirect_uristringOptional

Redirect URI. Required for the authorization_code grant type. It must match the redirect URI used to obtain the authorization code.

Example: https://example.com/oauth/callback

client_idstringOptional

Client ID.

client_secretstringOptional

Client secret.

code_verifierstringOptional

PKCE code verifier. Required for the authorization_code grant type.

refresh_tokenstringOptional

Refresh token. Required for the refresh_token grant type.

Responses

200

Token exchange response

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

4XX

OAuth error response

application/json

post

/api/v1/auth/token

HTTPcURLJavaScriptPython

POST /api/v1/auth/token HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 189

{
  "grant_type": "authorization_code",
  "code": "text",
  "redirect_uri": "https://example.com/oauth/callback",
  "client_id": "text",
  "client_secret": "text",
  "code_verifier": "text",
  "refresh_token": "text"
}

{
  "token_type": "Bearer",
  "access_token": "text",
  "expires_in": 1,
  "refresh_token": "text",
  "refresh_expires_in": 1,
  "scope": "text"
}

Revoke an auth session

post

Revoke an auth session from an access token or a refresh token.

Authorizations

client-authbasic-client

Header parameters

AuthorizationstringOptional

Basic auth credentials with client id and secret. If undefined, falls back to client id and secret in the body. Whatever the method, the client ID is required. Client without secret should use the body.

Body

application/json

Revoke access token or refresh token request body

tokenstringRequired

Token to revoke, either access or refresh token.

token_type_hintstring · enumOptional

Token type hint, indicating if the provided token is either an access or a refresh token.

Possible values:

client_idstringOptional

Client ID. Could be passed in the body or as a Basic Authorization header as the preferred method. Whatever the method, the client ID is required.

client_secretstringOptional

Client secret. Could be passed in the body or as a Basic Authorization header as the preferred method.

Responses

200

No content for the revoke response, as per OAuth specification.

No content

401

Unauthorized

application/json

500

Internal server error

application/json

post

/api/v1/auth/revoke

HTTPcURLJavaScriptPython

POST /api/v1/auth/revoke HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 91

{
  "token": "text",
  "token_type_hint": "access_token",
  "client_id": "text",
  "client_secret": "text"
}

No content

Get authorization scopes

get

Get all available authorization scopes.

Responses

200

Available authorization scopes retrieved successfully

application/json

500

Internal server error

application/json

get

/api/v1/auth/scopes

HTTPcURLJavaScriptPython

GET /api/v1/auth/scopes HTTP/1.1
Host: 
Accept: */*

{
  "scopes": [
    {
      "scope": "account",
      "description": "Access your basic account information and profile"
    }
  ]
}