Authentication
API key format, scopes, and MCP OAuth.
Authentication
Postato supports two authentication paths depending on the client.
REST API: Bearer API keys
Every REST request authenticates with an Authorization: Bearer <key> header.
Key format
API keys have the shape smcp_ followed by 64 hex characters. Example:
smcp_3f1a2b4c5d6e7f8091a2b3c4d5e6f7081a2b3c4d5e6f7089abcdef0123456789Keys are generated once and displayed in full only at creation. The server stores a SHA-256 hash; the plaintext cannot be recovered. If you lose a key, revoke it and create a new one.
The first 12 characters (smcp_xxxxxxx) act as a display prefix in dashboards and audit logs.
Scopes
An API key carries a scope that decides which workspaces it can act on:
| Scope | Behavior |
|---|---|
selected | Bound to a fixed list of workspaces (one or more). |
all | Follows the owning agent's current grants dynamically. Gaining access to a new workspace automatically extends the key. |
A "single workspace" key is just selected with one entry. Scope can be changed later by a tenant owner via the agent settings; workspace-managed agents have their scope locked to the workspace they were created in (see Workspaces).
Which workspace does a request target?
Workspace-scoped REST routes live under /v1/workspaces/{workspaceId}/.... The workspaceId in the path must be one the key is allowed to reach. If the caller has access to exactly one workspace, some convenience routes resolve it automatically; otherwise the workspace ID is required and missing ones return 400 workspace_required with the list of allowed workspaces in the response body.
Rotation
From Agents in the workspace nav (or Org settings → Agents for tenant-wide agents) you can revoke or rotate any key at any time. Revocation is immediate; in-flight requests using the key will fail on the next authentication check.
We recommend creating short-lived keys scoped to the narrowest workspace set the caller actually needs, and rotating on a schedule that matches your operational policy.
MCP: OAuth + API key
The MCP server accepts both Bearer API keys and OAuth access tokens issued via the MCP spec's authorization flow.
API key (simpler)
Same key format as REST. Pass it via Authorization: Bearer <key>. This is the fastest path for local agents or server-to-server integrations.
OAuth (for user-attended agents)
Claude Desktop, OpenAI custom GPTs, and other MCP clients that run on behalf of an end user will do a full OAuth flow against the Postato authorization server. You don't configure anything server-side; the flow is automatic once the client points at https://api.postato.com.br/mcp.
Scopes issued: mcp:tools. Access tokens are short-lived; refresh tokens handle long sessions.
Where keys are used
Authorization: Bearer smcp_...: REST API and MCP- Per-request
Idempotency-Key: see Idempotency X-Webhook-Signature: outbound webhook verification, see Webhooks