Cotal Exchange API

The Exchange API from Cotal — 1 operation(s) for exchange.

GitHub OpenAPI

Operations 1

POST /exchange Exchange an identity proof #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/cotal-ai:cotal-ai-exchange-api"
All apis
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.

Get an API 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 Specification

cotal-ai-exchange-api-openapi.yml Raw ↑
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