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.

Get Your Coworker Profiles

Use GET /api/sys/users/coworkers to retrieve the authenticated user’s customer profiles. The response groups profiles by their root location (network), which is useful when the same user belongs to more than one location or network.

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

Each network includes its root location and a Coworkers array. Each profile contains its ID, name, default-profile status, avatar URL, customer type, company name, and invoicing location. The response also includes the authenticated user in User.

{
  "Networks": [
    {
      "RootBusiness": {
        "Id": 1,
        "Name": "Network location",
        "WebAddress": "network"
      },
      "Coworkers": [
        {
          "Id": 42,
          "IsDefaultProfile": true,
          "FullName": "Alex Morgan",
          "AvatarUrl": "https://...",
          "CoworkerType": 1,
          "CompanyName": "Example Company",
          "InvoicingBusiness": {
            "Id": 1,
            "Name": "Home Location",
            "WebAddress": "location_a"
          }
        }
      ]
    }
  ],
  "User": {
    "...": "authenticated user details"
  }
}