Authentication

How to authenticate requests to the Nexudus REST API using Bearer tokens or Basic Auth

Authentication

All REST API endpoints require authentication unless otherwise noted. The API supports two authentication schemes: Bearer token (recommended) and Basic Auth.

Getting a Token

Use the POST /api/token endpoint to exchange a username and password for a bearer token.

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.

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

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

The client_id parameter is optional. If provided, you must use the same value when refreshing the token. If omitted, the username (email) is used as the client_id automatically.

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

grant_type=password&username=admin%40example.com&password=S3cur3P%40ss&client_id=my-app-identifier

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

Use the refresh_token to obtain a new access_token after it expires without requiring the user to re-enter their password. See Refresh a bearer token for details.

Two-Factor Authentication

If the user has 2FA enabled, include the totp parameter with their current TOTP code:

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

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

Bearer Token

Include the access_token in the Authorization header of every authenticated request:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://spaces.nexudus.com/api/spaces/coworkers

Bearer tokens are the recommended authentication method for server-to-server integrations and automated scripts.

Basic Auth

You can also authenticate using HTTP Basic Auth by passing your Nexudus username and password directly:

curl -u "[e-mail]:your-password" \
  https://spaces.nexudus.com/api/spaces/coworkers

Or by setting the Authorization header manually with a Base64-encoded username:password string:

curl -H "Authorization: Basic $(echo -n '[e-mail]:your-password' | base64)" \
  https://spaces.nexudus.com/api/spaces/coworkers

Basic Auth transmits credentials on every request. Prefer Bearer tokens for long-running integrations to reduce credential exposure.

Failed Authentication

When authentication fails or the account does not have permission for the requested resource, the API returns a 401 Unauthorized response.