Authentication and access

Every Mosoo API request uses a Bearer API token:

Authorization: Bearer mst_...

JSON requests also use:

Content-Type: application/json

Mosoo authenticates the API token, resolves the current Mosoo account, then checks whether that account can use the selected Agent API Endpoint and resource.

API tokens

An API token is the credential your code uses to call the Mosoo API. Create it in Mosoo account settings and store it in your app backend, local tools, or automation jobs.

Agent API Endpoint access

API access is available only after an Agent is published and has a live API endpoint version. A valid request must pass these checks:

1. The API token is present, valid, and not revoked.
2. The agentId is a v1 bare ULID for a real Agent.
3. The Agent is published.
4. The Agent has a live API endpoint version.
5. The API token owner owns the App that owns the Agent.
6. The Agent owner matches the App owner.

If the token is valid but the caller cannot consume the Agent, Mosoo returns 403 forbidden. If the Agent or resource is not visible to the caller, Mosoo returns 404 not_found.

Caller identity and execution

Threads created through the public API are attributed to the API token owner. Thread and file reads are visible to that owner when the underlying Agent API Endpoint is still accessible.

Runs execute with the published Agent configuration. The API caller does not become the model provider, cannot send provider credentials in the request, and cannot override tools, channels, runtime settings, or Agent configuration through this API.

Token lifecycle

Revoking an API token blocks future API requests from that token. It does not delete existing Threads.

Use separate API tokens for separate systems when possible:

• One API token for local development.
• One API token per server-side integration or automation.
• Clear API token labels for audit and rotation.

Safe retries

When retrying Thread creation or event submission, send the same Idempotency-Key.

Idempotency-Key: support-ticket-182-create-thread

The same key with the same request returns the original response. Reusing the key while the first request is still processing, or using it with a different request body, returns 409 idempotency_conflict.