Auth API · agents

The caller's consent on the authorization screen

PUT /api/auth/agents/{organizationId}/{clientId}

The caller's consent on the authorization screen: this MCP client may act as them in this organization, with the scopes they choose — closed (write implying read) and of what they hold there, never more.

The MCP token exchange reads the grant to mint the agent a organization token carrying the person's roles and the grant as agentScopes, and every service holds the two's overlap: owners and admins are narrowed too, and a person whose roles shrink takes their agent down with them. One client acts as one person in one organization at a time, so a grant for the client in another organization moves here. 400 AgentGrantEmpty when no scope asked for is one the caller holds, 400 AgentAuthorizationInvalid when oauthQuery is not an authorization request the provider signed for this client (tampered, hand-made, expired — the consent screen passes the one it was opened with), 403 NotAMember for anyone outside the organization, 404 AgentClientNotFound for an unregistered client. Appends auth.agent-connected. Idempotent by content: a grant already naming this organization and these scopes is acknowledged and appends nothing; other scopes are a change, and a new fact.

Access

Requires a signed-in session: Any active member of the organization, checked against its membership by the route: the consent is the caller's own, for themselves

How scopes come from roles: Scopes and roles. Getting a token: Authentication and app tokens.

Retries

Idempotent by content: a grant already naming this organization and these scopes is acknowledged and appends nothing; other scopes are a change, and a new fact.

Why every write carries a key: Idempotency and retries.

Facts appended

• auth.agent-connected

What a fact is: Facts and the journal.

AI agent tool

No agent tool. Consent is the person's, given on the authorization screen in a browser; an agent never consents for itself.

Connecting an agent: AI agents.

Example

curl -X PUT 'https://auth.getmanifold.io/api/auth/agents/org_01a156d2-8680-7738-ab2e-ff985e454887/kQ7vXpLmTsWnhRbyJdcFgzNaeHuVrKoB' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "scopes": [
    "orders:read",
    "stock:read",
    "products:read"
  ],
  "oauthQuery": "response_type=code&client_id=kQ7vXpLmTsWnhRbyJdcFgzNaeHuVrKoB&redirect_uri=http%3A%2F%2F127.0.0.1%3A33418%2Fcallback&scope=openid+offline_access&state=k2Jd8sQv&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&exp=1792634400&sig=Rk9yLWNvbnNlbnQtb25seQ"
}'

const response = await fetch("https://auth.getmanifold.io/api/auth/agents/org_01a156d2-8680-7738-ab2e-ff985e454887/kQ7vXpLmTsWnhRbyJdcFgzNaeHuVrKoB", {
  method: "PUT",
  headers: { Authorization: `Bearer ${process.env.MANIFOLD_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "scopes": [
      "orders:read",
      "stock:read",
      "products:read"
    ],
    "oauthQuery": "response_type=code&client_id=kQ7vXpLmTsWnhRbyJdcFgzNaeHuVrKoB&redirect_uri=http%3A%2F%2F127.0.0.1%3A33418%2Fcallback&scope=openid+offline_access&state=k2Jd8sQv&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&exp=1792634400&sig=Rk9yLWNvbnNlbnQtb25seQ"
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const answer = await response.json();

{
  "scopes": [
    "orders:read",
    "stock:read",
    "products:read"
  ],
  "oauthQuery": "response_type=code&client_id=kQ7vXpLmTsWnhRbyJdcFgzNaeHuVrKoB&redirect_uri=http%3A%2F%2F127.0.0.1%3A33418%2Fcallback&scope=openid+offline_access&state=k2Jd8sQv&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&exp=1792634400&sig=Rk9yLWNvbnNlbnQtb25seQ"
}

{
  "clientId": "kQ7vXpLmTsWnhRbyJdcFgzNaeHuVrKoB",
  "userId": "usr_01a15709-7582-7646-b491-261a138f0650",
  "organizationId": "org_01a156d2-8680-7738-ab2e-ff985e454887",
  "scopes": [
    "products:read",
    "stock:read",
    "orders:read"
  ],
  "grantedAt": "2026-10-22T01:12:09.000Z",
  "clientName": "Stockroom Assistant",
  "userEmail": "dana.whitlock@ridgeline-outdoor.example",
  "userName": "Dana Whitlock"
}

The panel writes this call in other languages. It does not send it: Manifold's APIs do not take calls from a web page on another site, so run the call from your own code or terminal. The whole API as OpenAPI: auth-service.openapi.json. Base URL https://auth.getmanifold.io.

Errors

Every refusal is a status and a JSON body whose _tag names it. A refused call changes nothing.

400

401

402

403

404

409

503

How refusals work everywhere: Errors.