Authentication System Description (Auth)

Description

Backend management interfaces use a multi-level authentication mechanism. From lowest to highest privilege: Public, User, Admin, Root.

Different interfaces use slightly different authentication methods — please cross-reference this page when calling them.

Authentication Methods

The backend management interfaces use one of the following two authentication methods. Note that the two tokens are different and must not be mixed up.

1. System Access Token (PAT) + New-Api-User

Used by the vast majority of backend management interfaces (user management, token management, log queries, etc.).

Send both headers together:

Authorization: Bearer {system_access_token}
New-Api-User: {user_id}

• {system_access_token}: A 32-character string generated under "Personal Settings → Security → System Access Tokens". This is not a sk-xxx style API Key.
• {user_id}: The ID of the currently logged-in user. It must match the owner of the token.
• The Bearer prefix in Authorization is optional — passing the raw token works too.
• A browser session cookie is also accepted, but you still need to send New-Api-User.

2. API Key (sk-xxx)

Only used by "query my own info as a token" endpoints, such as:

• GET /api/usage/token/ — Get token usage
• GET /api/log/token — Get logs by token

Only the API Key is required — New-Api-User is not needed:

Authorization: Bearer sk-xxxxxx

• The API Key is created under "Console → Token Management" and looks like sk-xxxxxx.
• The middleware for these endpoints identifies the user from the API Key itself, so any New-Api-User header is ignored.

Permission Levels

• Public: No authentication required.
• User: Requires session login or a System Access Token (PAT).
• Admin: Requires the PAT or session of an admin account.
• Root: Requires the PAT or session of a Root account.

Common Mistakes

• ❌ Calling a PAT-protected management endpoint (e.g. /api/token/, /api/user/self) with a sk-xxx API Key — authentication will fail.
• ❌ Sending New-Api-User along with /api/usage/token/ or /api/log/token while using a PAT — these endpoints only look at the API Key in Authorization, the user header has no effect.
• ❌ Omitting the New-Api-User header when calling a PAT-protected endpoint — the middleware will reject the request with 401.