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.
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:
Extract the access token
The response body contains your JWT token along with your role and user details:
Pass the token in the Authorization header
Include the token as a Bearer credential on every subsequent request:
Login request fields
Local username or email. When LDAP is enabled and no local password matches, Octop retries the same fields against the directory.
Local password, or the directory password when the account authenticates through LDAP.
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
A signed JWT token. Include this value as Bearer <access_token> in the Authorization header.
The account's role. Either "admin" or "user".
Basic profile information for the authenticated account.
user fields
Unique numeric identifier for the user.
The account's login username.
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.
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:
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:
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.
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.

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:
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.
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:
A successful response returns 204 No Content.
Error reference
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.

