Cotal Exchange API
The Exchange API from Cotal — 1 operation(s) for exchange.
The Exchange API from Cotal — 1 operation(s) for exchange.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/cotal-ai:cotal-ai-exchange-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Cotal Ai Exchange API
version: 1.0.0
description: 'Operations tagged Exchange across 2 of this provider''s published API definitions: cotal-ai-auth-openapi.json, cotal-ai-auth-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://auth.example.invalid
description: Replace with the configured HTTPS public authority URL; TLS terminates at the operator proxy.
tags:
- name: Exchange
paths:
/exchange:
post:
operationId: auth-exchange
summary: Exchange an identity proof
description: No loopback capability on this listener. Fresh pinned-issuer/audience IdP proof or managed ledger actor secret authorizes the selected actor. A successful human exchange includes the current grant the issuer authorized; a managed-agent exchange keeps the token, owner and exp response. Public views are channel-writer, channel-purger, manager-caller, session-caller and transfer-writer; other views return 403. ttlSec is constrained by issuer policy and proof expiry; agent bearer cap is 300 seconds. Invalid proof or manager selection returns 401. Refused proof/view attempts share the public peer budget; successful credentials still mint when the budget is full. Origin is refused.
security: []
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/Bearer'
'400':
$ref: '#/components/responses/RequestError'
'401':
$ref: '#/components/responses/RequestError'
'403':
$ref: '#/components/responses/RequestError'
'405':
$ref: '#/components/responses/RequestError'
'413':
$ref: '#/components/responses/RequestError'
'415':
$ref: '#/components/responses/RequestError'
'429':
$ref: '#/components/responses/RequestError'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/Unavailable'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExchangeRequest'
examples:
human:
summary: Human identity
description: Replace the placeholder with a fresh proof from the configured identity provider.
value:
actor: worker
idpToken: <idp-token>
managed:
summary: Managed agent
description: Replace the owner and secret with the managed agent grant.
value:
owner: <owner>
actor: worker
actorToken: <managed-agent-secret>
view: manager-caller
description: UTF-8 JSON; maximum 65536 bytes. An Authorization header does not replace the JSON proof.
tags:
- Exchange
servers:
- url: https://auth.example.invalid
description: Replace with the configured HTTPS public authority URL; TLS terminates at the operator proxy.
components:
responses:
RequestError:
description: JSON error from a named request refusal. Route guards run before proof evaluation; parser failures are 400 and byte overflow is 413.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
InternalServerError:
description: Server failure. An unexpected failure reaching the listener boundary returns only {"error":"internal server error"}; details are logged server-side. A route's named server failure may include its error code and outcome.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: internal server error
Unavailable:
description: Public admission cap (64 in flight), 10 second request deadline, or a route-specific unavailable read/effect. A service authority 503 may follow a binding; retain the request identity.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
error:
type: string
code:
type: string
outcome:
type: string
enum:
- not-executed
- executed
- unknown
required:
- error
Bearer:
type: object
properties:
token:
type: string
minLength: 1
owner:
type: string
minLength: 1
exp:
type: integer
minimum: 0
grant:
$ref: '#/components/schemas/UserAuthGrant'
required:
- token
- owner
- exp
UserAuthGrant:
type: object
description: Current issuer-authorized agent grant. Present for a human IdP exchange and absent for a managed-agent secret exchange.
properties:
scope:
type: array
items:
type: string
allowSubscribe:
type: array
items:
type: string
allowPublish:
type: array
items:
type: string
dmHistory:
const: own
required:
- scope
- allowSubscribe
- allowPublish
- dmHistory
additionalProperties: false
ExchangeRequest:
type: object
properties:
idpToken:
type: string
minLength: 1
owner:
type: string
minLength: 1
actor:
type: string
minLength: 1
actorToken:
type: string
minLength: 1
ttlSec:
type: number
view:
type: string
enum:
- channel-writer
- channel-purger
- manager-caller
- session-caller
- transfer-writer
managerInstanceId:
type: string
sessionGrant:
type: object
properties:
sessionId:
type: string
minLength: 1
endpoint:
type: string
minLength: 1
serving:
type: object
properties:
instanceId:
type: string
minLength: 1
epoch:
type: integer
minimum: 0
required:
- instanceId
- epoch
sig:
type: string
minLength: 1
v:
const: 1
space:
type: string
minLength: 1
subjects:
type: object
required:
- in
- out
properties:
in:
type: string
minLength: 1
out:
type: string
minLength: 1
holder:
type: object
required:
- id
- lifecycleUid
- processEpoch
properties:
id:
type: string
minLength: 1
lifecycleUid:
type: string
minLength: 1
processEpoch:
type: integer
minimum: 0
window:
type: integer
minimum: 0
iat:
type: integer
minimum: 0
nbf:
type: integer
minimum: 0
exp:
type: integer
minimum: 0
nonce:
type: string
minLength: 1
issuer:
type: object
required:
- keyId
properties:
keyId:
type: string
minLength: 1
required: []
description: Transport envelope only. Nested native fields and operation-specific constraints are defined by SessionGrant in the linked source; this schema is not a complete native command contract.
x-native-contract:
name: SessionGrant
url: https://github.com/Cotal-AI/Cotal/blob/main/packages/core/src/endpoint-session.ts
transferWriter:
type: object
properties:
instanceId:
type: string
minLength: 1
hex:
type: string
minLength: 1
required:
- instanceId
- hex
required:
- actor
description: Provide idpToken for a human OR owner plus actorToken for a managed agent, never both. Agent view may only be manager-caller. managerInstanceId requires manager-caller; sessionGrant accompanies session-caller; transferWriter accompanies transfer-writer. Native SessionGrant is verified against the redeemed session ledger; the nested schema documents its transport shape only.
oneOf:
- required:
- idpToken
not:
required:
- actorToken
title: Human identity
- required:
- owner
- actorToken
not:
required:
- idpToken
title: Managed agent
x-refined-from:
- cotal-ai-auth-openapi.json
- cotal-ai-auth-openapi.yml
x-source: implementations/auth/src/service.ts ROUTES and loopback handlers