Agentra Authorizations API

openapi: 3.2.0
info:
  title: Agentra - Identity Oracle and Trust Layer for AI Agents…
  version: 1.0.0
  description: 'Non-custodial authorization infrastructure for autonomous AI agents.

    Agentra verifies agent identity, scores bidirectional trust, and

    orchestrates payment authorizations without ever touching private

    keys or custodying funds.


    ## Architecture


    Agentra is an identity oracle, not a payment processor. The flow:

    1. Agent requests authorization via this API

    2. Agentra verifies identity + scores trust + checks limits

    3. Returns attestation + unsigned transaction

    4. Agent signs with their own Turnkey wallet

    5. Agent submits signed transaction to Base network

    6. Agent calls settle endpoint to record completion


    ## Quick Start (2 API calls)


    1. POST /v1/agents/register - Get agent_id and API key

    2. POST /v1/wallets/provision - Provision a Turnkey wallet


    ## Authentication


    All endpoints require X-API-Key header with your agent key (agn_ prefix)

    or service key (ask_ prefix).


    ## MCP Alternative


    This same API is available via MCP (Model Context Protocol) at

    POST /mcp for Claude, Cursor, and other MCP-native agents.'
  contact:
    name: Agentra
    url: https://agentrapay.ai
  license:
    name: Proprietary
    identifier: LicenseRef-Agentra
servers:
- url: https://api.agentrapay.ai
  description: Production (Base Mainnet mainnet)
security:
- ApiKeyAuth: []
tags:
- name: Authorizations
paths:
  /v1/authorizations:
    post:
      operationId: createAuthorization
      summary: Request payment authorization
      description: 'Request authorization for a payment. NON-CUSTODIAL: returns an

        authorization attestation and unsigned transaction data. Agentra

        never touches private keys.


        If require_counterparty_kya is true (default) and the counterparty

        is not registered, returns a 402-style challenge with instructions

        for the counterparty to onboard.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizationRequest'
      responses:
        '201':
          description: Authorization granted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResponse'
        '402':
          description: Counterparty KYA required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KyaChallenge'
          headers:
            Link:
              description: Discovery breadcrumb for unregistered agents
              schema:
                type: string
                example: <https://agentrapay.ai/llms.txt>; rel="help"
            X-Agent-Onboard:
              description: MCP endpoint for self-service onboarding
              schema:
                type: string
                example: https://api.agentrapay.ai/mcp
        '403':
          description: Amount exceeds tier limits
      tags:
      - Authorizations
  /v1/authorizations/{authorization_id}/settle:
    post:
      operationId: settleAuthorization
      summary: Record settlement of an authorization
      description: 'After signing and submitting the transaction yourself, call this

        endpoint to record the settlement. Provide the on-chain transaction hash.'
      parameters:
      - name: authorization_id
        in: path
        required: true
        schema:
          type: string
      tags:
      - Authorizations
components:
  schemas:
    AuthorizationResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    AuthorizationRequest:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    KyaChallenge:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true