Skip to main content

​
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/sys/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 "admin@example.com:your-password" \
  https://spaces.nexudus.com/api/sys/coworkers
Or by setting the Authorization header manually with a Base64-encoded username:password string: 
curl -H "Authorization: Basic $(echo -n 'admin@example.com:your-password' | base64)" \
  https://spaces.nexudus.com/api/sys/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.