Management API authentication and migration

Version and API origin

This page targets new-api v1.0.0-rc.44, checked on 2026-10-15. Use https://api.beeaicloud.com for management requests. The documentation domain is not the API origin. Native /api/, BeeBridge /management-api/ and /integration-api/ have separate contracts, sessions and error envelopes.

Three distinct credentials

A session access_token is a short-lived Bearer credential issued by password or OAuth sign-in and used for session/PAT management. A management PAT starts with nap_ and grants only selected management permissions; it cannot create or manage PATs. A model API key is for inference routes such as /v1/, not management authentication. Using the same Authorization header does not make them interchangeable. New-Api-User is not an account selector or proof of identity; the server derives identity from the credential.

First call GET /api/user/login/encryption-key. When enabled=true, both sign-in and password verification submit password_encrypted and encryption_key_id, using the returned kid. Base64 RSA-OAEP/SHA-256 ciphertext is supported. For long passwords, v2 wraps a fresh 32-byte AES key using RSA-OAEP with label password-v2; AES-256-GCM uses a 12-byte nonce and AAD password-v2:{kid}, with the 16-byte tag appended to ciphertext. Format: v2.{wrappedKeyBase64}.{nonceBase64}.{ciphertextAndTagBase64}. Send plaintext password only when encryption is disabled, still over HTTPS.

After POST /api/user/login, check data.require_verification. If true, complete the flow indicated by data.methods with flow_token, via /api/user/login/verify or the dedicated Passkey flow. Use the final data.access_token. Sign-in verification differs from the operation proof at /api/verify. Refresh uses POST /api/user/auth/refresh with the new_api_refresh cookie; sign-out uses POST /api/user/auth/logout. Cookie requests enforce Origin checks; do not forge Origin to bypass them.

Operation verification

Call GET /api/verify/methods?scope=access_token.generate and select a method with available=true. Then submit method, operation scope and its strict context to POST /api/verify. Use data.proof_token once through X-Security-Proof, with the same identity/session and exact operation context. Passkey and OAuth require dedicated interactive flows; merely changing method in the universal endpoint is insufficient.

Management PATs and permissions

Use the signed-in session to read /api/user/access_tokens/catalog and select permissions needed by the integration. profile:read only reads your profile; it does not grant API-key management, all usage queries or wallet operations. /api/user/access_tokens/scopes is a label dictionary, not the current account grant catalog. Account state, role and current authorization still limit PAT access.

Failures and retries

Check both HTTP status and success. Codes may be in code or data.code; HTTP 200 may contain a business rejection. For 400 SECURITY_CONTEXT_INVALID, inspect context first; for 401, inspect the credential/session; for 403, inspect session requirements, scopes and account permissions. For 429, stop tight retries and respect backoff. If a create/revoke/update response is lost, reconcile state before repeating the write. Log only sanitized codes, timestamps and request IDs, never passwords, ciphertext, cookies, PATs or proofs.

Legacy migration

Old GET/POST /api/user/token is no longer a PAT issuance endpoint: use POST /api/user/access_tokens. Replace GET /api/user/logout with POST /api/user/auth/logout. Replace GET /api/verify/status with scope-specific /api/verify/methods; obtain proofs from verification responses. Replace GET /api/oauth/state with POST /api/oauth/state. An existing legacy PAT may remain valid during the configured transition without preserving the old issuance flow. Read its deadline from data.legacy.retire_at in the PAT list rather than hardcoding a date. Public native registration is closed at the current production ingress; an upstream route does not itself authorize account creation.

PAT →