> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api/endpoints/auth/get-token) endpoint to exchange a username and password for a bearer token.

<Note>
  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.
</Note>

```http theme={null}
POST /api/token
Content-Type: application/x-www-form-urlencoded

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

```json theme={null}
{
  "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.

### Two-Factor Authentication

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

```http theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
curl -H "Authorization: Basic $(echo -n 'admin@example.com:your-password' | base64)" \
  https://spaces.nexudus.com/api/sys/coworkers
```

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

## Failed Authentication

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