> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# Authenticate and Authorize All Requests to the Octop API

Every Octop API call — except `/api/health`, `/api/setup/*`, `/api/auth/captcha`, public SSO start/callback/exchange routes, invite redeem, and the OpenAPI schema — requires a JWT access token. Obtain the token by logging in with your credentials, then include it in the `Authorization` header of every subsequent request. Tokens expire after 24 hours by default; re-login to get a fresh one.


> **WARNING**
> 
> First-run credentials depend on how you installed Octop. After a bare-metal `octop init` / setup wizard, open `~/octop-login.txt` for the one-time setup password, then sign in with the admin username and password you created. After Docker first boot, sign in as `admin` (or `OCTOP_ADMIN_USERNAME`) with the password in `/data/.octop/credential.txt` (`docker exec octop cat /data/.octop/credential.txt`). Octop generates a random password unless you set `OCTOP_DEFAULT_PASSWORD`; weak values fall back to a random password. Use those credentials for API login.
> 


## Log in and get a token


### POST your credentials

Send your `username` and `password` to the login endpoint:

```bash cURL
curl -X POST http://127.0.0.1:8088/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username": "<your_username>", "password": "<your_password>"}'
```
```python Python
import requests

resp = requests.post(
    "http://127.0.0.1:8088/api/auth/login",
    json={"username": "<your_username>", "password": "<your_password>"},
)
token = resp.json()["access_token"]
```


### Extract the access token

The response body contains your JWT token along with your role and user details:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "role": "admin",
  "user": {
    "id": 1,
    "username": "admin",
    "display_name": "Administrator"
  }
}
```

### Pass the token in the Authorization header

Include the token as a Bearer credential on every subsequent request:

```bash cURL
curl http://127.0.0.1:8088/api/agents \
  -H 'Authorization: Bearer <your_token>'
```
```python Python
headers = {"Authorization": f"Bearer {token}"}
agents = requests.get(
    "http://127.0.0.1:8088/api/agents",
    headers=headers,
).json()
```


### Login request fields


- `username` (string, body, required)

Local username or email. When LDAP is enabled and no local password matches, Octop retries the same fields against the directory.


- `password` (string, body, required)

Local password, or the directory password when the account authenticates through LDAP.


- `captcha_token` (string, body)

Required when a strong captcha provider is active (`turnstile`, `hcaptcha`, `recaptcha`, `recaptcha-v3`, or `tencent`). Maximum 4096 characters. For `tencent`, send the callback pair as `ticket:randstr`. The default `slider` is dashboard-only and is not checked here.

### Login response fields


- `access_token` (string)

A signed JWT token. Include this value as `Bearer <access_token>` in the `Authorization` header.


- `role` (string)

The account's role. Either `"admin"` or `"user"`.


- `user` (object)

Basic profile information for the authenticated account.

**user fields**


- `user.id` (integer)

Unique numeric identifier for the user.

- `user.username` (string)

The account's login username.

- `user.display_name` (string)

The human-readable display name shown in the web UI.

## Token expiry

Tokens expire after **24 hours** by default. Control this with the `OCTOP_ACCESS_TOKEN_TTL` environment variable (value in seconds). When a token expires, re-call `POST /api/auth/login` to obtain a fresh one.


> **NOTE**
> 
> Rotating the JWT secret via `octop admin rotate-jwt-secret` immediately invalidates **all** outstanding tokens. Every user must re-login after a rotation.
> 


## Get current user info

Retrieve the profile of the currently authenticated user:

```bash
curl http://127.0.0.1:8088/api/auth/me \
  -H 'Authorization: Bearer <token>'
```

The response includes `id`, `username`, `role`, `display_name`, `locale`, plus SSO fields: `sso_identities` (linked `{kind}` rows), `sso_linked`, `sso_kind` (first linked kind), and `has_password`.

## Change password

Update your own password without admin involvement:

```bash
curl -X POST http://127.0.0.1:8088/api/auth/change-password \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"old_password": "octop", "new_password": "mysecurepass1"}'
```

A successful response returns `204 No Content`.

New passwords must be at least **8** characters, include a letter and a digit, differ from the current password, and must not be on a small denylist of common strings (for example `password123` or `admin123`).

## Login captcha

`GET /api/auth/captcha` returns `{provider, site_key?}` for the login widget. It is public, and returns `503` while first-run setup is still required. Default `provider` is `slider` (dashboard only; the API does not verify a token).

When a strong provider is active, `POST /api/auth/login` must include `captcha_token`. Captcha failures do **not** increment login lockout. OIDC and OAuth login skip this check.

Configure the provider under **Management → App settings**, or with `OCTOP_CAPTCHA_*` (boot snapshot; restart after you change env). `GET` / `PUT /api/settings/captcha` require the `captcha` permission. Secrets are omitted from GET; sending an empty secret on PUT keeps the stored value.

If a settings-sourced strong provider locks everyone out, run `octop captcha reset` and restart `octop run`. If boot env (`OCTOP_CAPTCHA_*`) is the cause, edit `~/.octop/env` on disk — the dashboard is unreachable until the process starts.

## Single sign-on

An administrator enables SSO under **Management → Users → Single sign-on**. After at least one user exists, the login page can show **Continue with \{name}** for each enabled provider.

### OpenID Connect

The web UI includes quick-start presets for **Azure AD**, **Google**, **Keycloak**, and **Okta**. Pick a preset to fill common scopes, enter the issuer URL and OAuth client credentials, then copy the generated redirect URI into your identity provider. Save before you click **Test connection**; Octop tests the saved discovery settings.

| Method | Path                     | Who can call it | What it does                                           |
| ------ | ------------------------ | --------------- | ------------------------------------------------------ |
| `GET`  | `/auth/oidc/status`      | anyone          | Whether SSO is on, and the button label                |
| `POST` | `/auth/oidc/start`       | anyone          | Start the identity-provider login                      |
| `GET`  | `/auth/oidc/callback`    | anyone          | Return from the identity provider                      |
| `POST` | `/auth/oidc/exchange`    | anyone          | Finish login and return the same JWT as password login |
| `GET`  | `/auth/oidc/config`      | admin           | Read SSO settings (secret is hidden)                   |
| `PUT`  | `/auth/oidc/config`      | admin           | Save SSO settings                                      |
| `POST` | `/auth/oidc/config/test` | admin           | Test that the provider is reachable                    |

### LDAP directory login

Under **Management → Users → LDAP**, connect Active Directory, OpenLDAP, or a similar directory. People keep using the normal username/password form; Octop tries the local password first, then the directory.


![LDAP directory login](/images/en/ui-ldap.png "LDAP")

Typical setup: server URL (`ldaps://` preferred), bind account, search base and `{username}` filter, optional admin groups, then **Save** and **Test connection**, and turn LDAP on. Role mapping from directory groups applies only when Octop creates the account; later group changes do not silently promote users.

A hostname or public address must use `ldaps://` or `ldap://` with StartTLS. A literal private or loopback address (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `127.0.0.0/8`, `::1`) may use plain `ldap://`. The page warns that the password then travels in clear text.

When automatic provisioning is off, create a **Directory account** under **User management** before that person signs in. The username must match the directory login name, and the account has no local password. `POST /api/auth/change-password` then returns `400 PASSWORD_NOT_SET`. If the directory is unreachable, the API returns `502 LDAP_UNAVAILABLE` (unless a local password already matched). A directory user who was never created gets `403 LDAP_USER_NOT_PROVISIONED`.

### Account security

Open **Account security** to add a second check after the password. You can use an **Authenticator app**, a **Passkey**, recovery codes, or more than one of those.

Passkey sign-in on the login page is off until an administrator turns on **Show “Sign in with a passkey” on the login page** under **Application Settings → Passkeys**. Passkeys already added still work as a second factor. Passkeys need HTTPS, or `http://localhost`. They do not work on an IP address such as `127.0.0.1`.

`GET /auth/passkey/status` returns `{passwordless_login}` for the login page. Administrators read and save the relying-party settings with `GET` and `PUT /settings/webauthn`.

Changing the password invalidates outstanding access tokens. `POST /auth/change-password` returns a replacement in the `X-Octop-Access-Token` response header. An active session is renewed once less than two-thirds of `OCTOP_ACCESS_TOKEN_TTL` remains.

If someone is locked out of the authenticator and every passkey, clear the factors on the server without changing the password:

```bash
octop user reset-mfa <username>
```

### Feishu, DingTalk, and WeCom

The same users page also configures **Feishu**, **DingTalk**, **WeCom**, and **OIDC** on their own tabs. Enter the OAuth client id and secret, copy the generated callback URL into the provider console, then save and **Test connection**. WeCom also needs `extra.agent_id`.

A signed-in user can bind or unbind these identities. Unbinding the last login method requires a local password.

| Method | Path                                | Who can call it | What it does                                                                                            |
| ------ | ----------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------- |
| `GET`  | `/auth/oauth/status`                | anyone          | `{providers:[{kind, display_name, enabled}]}`                                                           |
| `POST` | `/auth/oauth/start`                 | anyone          | Body `{kind, redirect_after?}` → authorization URL (`kind` is `oidc`, `feishu`, `dingtalk`, or `wecom`) |
| `GET`  | `/auth/oauth/callback`              | anyone          | Provider callback (`code`, or DingTalk `authCode`)                                                      |
| `POST` | `/auth/oauth/exchange`              | anyone          | Same one-time code exchange as `/auth/oidc/exchange`                                                    |
| `POST` | `/auth/oauth/bind/start`            | user            | Bind the identity to the current user                                                                   |
| `POST` | `/auth/oauth/unbind`                | user            | Unlink one SSO identity by `kind`                                                                       |
| `GET`  | `/auth/oauth/providers/{kind}`      | `sso`           | Provider config; `client_secret` is omitted                                                             |
| `PUT`  | `/auth/oauth/providers/{kind}`      | `sso`           | Upsert provider config; `client_secret` is write-only                                                   |
| `POST` | `/auth/oauth/providers/{kind}/test` | `sso`           | Test provider credentials                                                                               |

New SSO users get a regular user account. Grant settings access afterwards if they need it. The older `/auth/oidc/config` routes still work for the OIDC provider.

## Redeem an invite

Anyone with an invite link can call these routes. Administrators create invites from **Management → Users** or `POST /api/users/invites`. See [Users & Admin](/en/api/users-admin.md).

| Method | Path                    | What it does                     |
| ------ | ----------------------- | -------------------------------- |
| `POST` | `/auth/invite/validate` | Check that a code is still valid |
| `POST` | `/auth/invite/redeem`   | Create the user and return a JWT |

## Log out

Invalidate the current token server-side:

```bash
curl -X POST http://127.0.0.1:8088/api/auth/logout \
  -H 'Authorization: Bearer <token>'
```

A successful response returns `204 No Content`.

## Error reference

| HTTP Status        | Error Code      | Cause                                                                             | Resolution                                                                               |
| ------------------ | --------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `401 Unauthorized` | `AUTH_FAILED`   | Invalid credentials supplied at login                                             | Check username and password                                                              |
| `401 Unauthorized` | `TOKEN_EXPIRED` | JWT has passed its TTL                                                            | Re-login to obtain a fresh token                                                         |
| `403 Forbidden`    | `FORBIDDEN`     | Authenticated but insufficient role (e.g., non-admin accessing an admin endpoint) | Log in with an account that has the required role                                        |
| `403 Forbidden`    | `USER_DISABLED` | The account has been disabled by an admin                                         | Contact your Octop administrator                                                         |
| `423 Locked`       | `LOGIN_LOCKED`  | Too many failed login attempts; account is locked                                 | Wait out the lockout period, or ask an admin to call `POST /api/users/{id}/unlock-login` |


> **TIP**
> 
> Set `OCTOP_ENABLE_API_DOCS=1` (or `"enable_api_docs": true` in `config.json`) and visit `http://127.0.0.1:8088/api/docs` to explore every endpoint interactively with the built-in Scalar interface — no extra tooling required.
> 

