Get a bearer token

Exchange a customer email and password for a bearer token used to authenticate all subsequent API requests.

Get a bearer token

cURL

curl --request POST \
  --url https://spaces.nexudus.com/api/token \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "grant_type": "<string>",
  "username": "<string>",
  "password": "<string>"
}
'

import requests

url = "https://spaces.nexudus.com/api/token"

payload = {
    "grant_type": "<string>",
    "username": "<string>",
    "password": "<string>"
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({grant_type: '<string>', username: '<string>', password: '<string>'})
};

fetch('https://spaces.nexudus.com/api/token', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

200

{
  "access_token": "<string>",
  "token_type": "<string>",
  "expires_in": 123,
  "refresh_token": "<string>",
  "400 Bad Request — unsupported_grant_type": {},
  "400 Bad Request — invalid_grant": {},
  "400 Bad Request — two_factor_auth_check": {},
  "400 Bad Request — must_reset_password": {}
}

Get a bearer token

Exchanges a customer’s email address and password for a short-lived bearer token and a refresh token. Every authenticated API call in the Members Portal uses the access_token returned here as a Bearer credential. Pass totp when the customer has two-factor authentication enabled — omitting it when 2FA is active will return a two_factor_auth_check error.

Unlike most Nexudus API endpoints, this request must be encoded as application/x-www-form-urlencoded, not application/json. Sending a JSON body will result in an unsupported_grant_type error.

Authentication

No authentication required. This is the endpoint that issues credentials.

Request Body

grant_type · string · required

Grant flow to use. Must be password for email/password authentication.

username · string · required

The customer’s email address.

password · string · required

The customer’s password.

totp · string

Time-based One-Time Password for two-factor authentication. Required when the customer has 2FA enabled; omit otherwise.

Headers

client_id · string

A unique identifier for the client application or integration. If omitted, this defaults to the customer’s email address, which you must then use as the client_id when refreshing the token.

Response

access_token · string

Bearer token to include in the Authorization header of all subsequent authenticated requests.

token_type · string

Token scheme. Always bearer.

expires_in · number

Lifetime of the access token in seconds.

refresh_token · string

Token used to obtain a new access_token after it expires, without requiring the customer to re-enter their password.

Examples

Successful sign-in

POST /api/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=jane.doe%40example.com&password=S3cur3P%40ss

Sign-in with client identifier

Providing a client_id is optional. If you provide one, you must use the same value when refreshing the token. If omitted, the customer’s email address is used as the client_id, which you must then pass to the refresh endpoint.

POST /api/token
Content-Type: application/x-www-form-urlencoded
client_id: my-app-identifier

grant_type=password&username=jane.doe%40example.com&password=S3cur3P%40ss

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "8xLOxBtZp8"
}

Sign-in with two-factor authentication

POST /api/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=jane.doe%40example.com&password=S3cur3P%40ss&totp=482910

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "8xLOxBtZp8"
}

TypeScript Integration

import { type AxiosResponse } from 'axios'
import qs from 'qs'
import { AuthToken } from '@/states/useAuthContext'

const data = {
  grant_type: 'password',
  username: values.email,
  password: values.password,
  totp: values.totp,
}

const res: AxiosResponse<AuthToken> = await httpClient.post('/api/token', qs.stringify(data), {
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'client_id': values.clientId, // or email if omitted during sign-in
  },
})

if (res.data.access_token) {
  saveSession({ tokenResponse: res.data, remember: values.rememberMe })
}

Usage in Portal

Context	Source file
Sign-in page (/signin)	src/views/auth/SignIn/useSignIn.ts

Error Responses

400 Bad Request — unsupported_grant_type · error

The grant_type field is missing or the body was not encoded as application/x-www-form-urlencoded.

400 Bad Request — invalid_grant · error

Credentials are incorrect, the customer is not registered with this location, or the account has been suspended. The error_description field contains a human-readable reason.

400 Bad Request — two_factor_auth_check · error

The customer has 2FA enabled but totp was not supplied or the supplied code is invalid. Prompt the customer for their one-time code and retry.

400 Bad Request — must_reset_password · error

The customer is required to reset their password before signing in. The error_description field contains a password-reset token to pass to the reset-password flow.

Related Endpoints

Method	Endpoint	Description
POST	/api/token	(this endpoint) Exchange credentials for a bearer token
GET	/api/public/billing/customer	Retrieve the authenticated customer’s profile
GET	/api/public/teams/my	List teams the authenticated customer belongs to