Authentication and access
How API tokens, Agent API Endpoints, and Thread visibility work together.
Every application API request uses a Project API key:
Authorization: Bearer msp_...
Content-Type: application/jsonCreate and protect a key
Open the target Project settings → Project API keys and create a key. Copy it when it is shown: the secret is displayed once and only its hash is stored. Keep it on a trusted backend, never in browser or mobile client code.
A Project can have multiple keys. Every key belongs to exactly one Project and has the same supported Agent configuration, Session, and file access; configurable key scopes are not available. Project keys cannot manage accounts, Projects, or other keys. Provider and MCP credentials are configured separately and are not application API keys.
Agent API Endpoint access
The Public Thread API still requires a published Agent with a live API endpoint version. The key must be valid, not revoked, and belong to the Agent's Project. The account owning that Project must also own the Agent. Owning both Projects does not let an application key cross between them.
An unpublished Agent returns 409 agent_not_published; a missing live endpoint version returns 409 service_inactive. Access denial can return 403 forbidden or 404 not_found depending on the resource boundary.
Caller identity and execution
Your backend authenticates its end user and supplies a required opaque userId when creating a Thread. mosoo preserves the immutable (Project, userId) context for the Thread, Runs, files, and delegated MCP calls; it does not authenticate your end user. Your backend remains responsible for authorizing access to the stored Thread ID.
Runs use the published Agent configuration. Thread API requests cannot override provider credentials, tools, runtime settings, or Agent configuration.
Rotation and migration
Create a replacement key in the same Project, update the integration, then revoke the old key. Revocation rejects future requests from that key but does not stop admitted work or delete Threads. Another active key in the same Project, or the Project owner, can operate existing Threads.
Legacy mst_ and grt_pat_ tokens are rejected. They are not assigned to a default Project. Create a new key for each target Project and replace stored integration credentials. CLI users must sign in again with the current CLI; browser/CLI login provides account control-plane access and CLI login credentials use the distinct mcli_ prefix. A Project key is not an account login replacement.
Safe retries
Reuse the same Idempotency-Key for a retry of the same operation and body. Project keys share idempotency receipts and rate limits within the Project, so rotating keys neither creates duplicate work nor resets the limit. Use distinct operation IDs for separate integrations in the same Project.
The same key and request replay the original response. An in-flight request or different body using that key returns 409 idempotency_conflict.