Skip to main content

​
Authentication and access

The Mosoo API separates who is calling from which published Agent is allowed to run. Every request uses a bearer token: 
Authorization: Bearer grt_pat_...
The token identifies the caller. The agentId identifies the published Agent. Mosoo checks both before it creates or changes a Thread.

​
Token types

Human PAT

A long-lived token for a registered user. Use it for curl, local tools, user-owned integrations, and API calls that should be attributed to that person.

Organization Service token

A machine caller token for server-side integrations, CI/CD, Managed CLI, and scheduled jobs. It must be allowed to call selected published Agents.
Service tokens are not channel connection credentials. Slack, Lark, Discord, Telegram, WeChat, and other channel setup stays in Mosoo.

​
Published Agent access

API access is available only after an Agent is configured and published. A valid request must pass these checks:
  1. The Agent exists.
  2. The Agent is published and has API Access enabled.
  3. The bearer token is valid and not revoked.
  4. The caller is allowed to use the Agent.
  5. The requested Thread or file is visible to that caller.

​
Caller access paths

Access pathWho can call
Organization-wideActive Organization members with a valid Human PAT, plus allowed Service tokens.
Invited-onlyThe Agent owner, explicitly invited collaborators, and allowed Service tokens.
Selected Agent service accessOrganization Service tokens that explicitly include this published Agent.
Having a token is not enough. If the caller does not pass the Agent access check, Mosoo returns 403 Forbidden.

​
Attribution and execution

Mosoo records the API caller for access checks, attribution, audit logs, and Thread visibility. Runs still use the published Agent owner’s configured capabilities. The API caller does not become the Agent owner, change the Agent’s model provider, or supply provider credentials in the request. For Human PAT calls, the caller is the token owner. For Organization Service token calls, the request may omit user attribution or include attributed_user_id when that token is allowed to associate work with a bound user. 
{
  "attributed_user_id": "user_01KQX1BOUNDHUMAN7Z8",
  "client_external_ref": "support-ticket-182",
  "input": {
    "type": "user.message",
    "content": [
      {
        "type": "text",
        "text": "Triage this customer escalation."
      }
    ]
  }
}

​
Token lifecycle

Create and revoke tokens from Mosoo. Revoking a token blocks future API requests from that token; it does not delete existing Threads. Use separate tokens for separate systems when possible:
  • one Human PAT for local development,
  • one Service token per server-side integration or automation,
  • selected published Agents for Service tokens,
  • clear token labels for audit and rotation.

​
Idempotency

Use Idempotency-Key for retry-safe create-thread and send-events calls. 
-H "Idempotency-Key: support-ticket-182-create-thread"
Reusing the same key with the same request returns the original response. Reusing it while the first request is still processing, or with a different request, returns a conflict.