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.

#Log in and get a token

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

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"]

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "role": "admin",
  "user": {
    "id": 1,
    "username": "admin",
    "display_name": "Administrator"
  }
}

curl http://127.0.0.1:8088/api/agents \
  -H 'Authorization: Bearer <your_token>'

headers = {"Authorization": f"Bearer {token}"}
agents = requests.get(
    "http://127.0.0.1:8088/api/agents",
    headers=headers,
).json()

#Login request fields

#Login response fields

#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.

#Get current user info

Retrieve the profile of the currently authenticated user:

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:

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.

#Feishu, DingTalk, and WeCom

The same Single sign-on panel also configures Feishu, DingTalk, and WeCom. 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.

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.

#Log out

Invalidate the current token server-side:

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