FLINT Network Agent Sessions API

openapi: 3.2.0
info:
  title: FLINT Agent Transaction Control Agent Sessions API
  version: 1.0.0
  description: FLINT verifies agent authority before autonomous economic activity, issues signed verification records, accepts outcome feedback, and returns partner-safe Trust Graph reputation.
  x-guidance: 'Use POST /api/x402/scan for a $0.01 x402-paid bounded pre-transaction scan of a separate intended commerce transaction. Use POST /api/x402/verify for high-assurance $0.01 x402-paid agent-authority verification after obtaining the required FLINT capability and DPoP proof. Free operations are explicitly marked with security: [].'
  contact:
    name: FLINT Support
    email: support@flint.network
    url: https://flint.network
  license:
    name: Proprietary
    identifier: LicenseRef-FLINT-Proprietary
servers:
- url: https://flint.network
  description: Production
security: []
tags:
- name: Agent Sessions
  description: 'Email OTP sign-in for agents: request and verify a one-time code, then use the returned bearer session token wherever a browser session cookie is accepted.'
paths:
  /api/auth/otp-request:
    post:
      x-flint-release-state: staging
      security: []
      tags:
      - Agent Sessions
      operationId: requestAgentOtp
      summary: Request a one-time sign-in code by email
      description: 'The agent-native front door: an MCP agent (or the SPA) calls this first with an inbox address, reads the code WorkOS Magic Auth sends to that inbox, then calls POST /api/auth/otp-verify. Rate limited to 5 requests per email and 20 per IP per 10 minutes. Never echoes the code.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OtpRequestRequest'
      responses:
        '200':
          description: Code sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtpRequestResponse'
        '400':
          description: invalid_email.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: otp_rate_limited, with reason "ip", "email", or "provider".
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: auth_provider_error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: 'auth_not_configured: WORKOS_API_KEY or WORKOS_CLIENT_ID is not set.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/otp-verify:
    post:
      x-flint-release-state: staging
      security: []
      tags:
      - Agent Sessions
      operationId: verifyAgentOtp
      summary: Verify a one-time code and mint a session
      description: Verifies the WorkOS Magic Auth code from POST /api/auth/otp-request and mints both a browser session cookie (so this endpoint also serves the SPA) and a bearer agent session token, so an MCP agent can authenticate without ever holding a cookie. Runs the same new-account onboarding side effects as the browser OAuth callback. Never echoes the code.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OtpVerifyRequest'
      responses:
        '200':
          description: Signed in.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtpVerifyResponse'
        '400':
          description: otp_invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: otp_rate_limited, with reason "ip" or "provider".
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: auth_provider_error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: auth_not_configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/auth/session-revoke:
    post:
      x-flint-release-state: staging
      security:
      - bearerAgentSession: []
      tags:
      - Agent Sessions
      operationId: revokeAgentSession
      summary: Revoke the presented bearer agent session
      description: 'Ends a session_token immediately instead of waiting for its TTL. Idempotent: revoking an already-revoked or unknown token still returns ok.'
      responses:
        '200':
          description: Revoked (or already revoked/unknown; idempotent).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionRevokeResponse'
        '401':
          description: 'not_authenticated: no bearer token was presented.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SessionRevokeResponse:
      type: object
      properties:
        ok:
          type: boolean
    OtpVerifyRequest:
      type: object
      required:
      - email
      - code
      properties:
        email:
          type: string
          format: email
        code:
          type: string
          description: The one-time code delivered to the inbox by /api/auth/otp-request.
        label:
          type: string
          maxLength: 120
          description: Optional human-readable label for the resulting session, such as the agent or workflow name.
    OtpRequestRequest:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
    OtpRequestResponse:
      type: object
      properties:
        ok:
          type: boolean
        email:
          type: string
          format: email
        delivery:
          type: string
          enum:
          - email
        expires_in_seconds:
          type: integer
    OtpVerifyResponse:
      type: object
      properties:
        ok:
          type: boolean
        session_token:
          type: string
          description: 'Bearer agent session token ("flint_sess_" prefix). Pass it as Authorization: Bearer <session_token> on later calls. Treat it like a password; never log it.'
        expires_at:
          type: string
          format: date-time
        user:
          type: object
          properties:
            id:
              type: string
            email:
              type: string
              format: email
            email_verified:
              type: boolean
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
        error:
          type: string
        detail:
          type: string
  securitySchemes:
    WorkOSOwnerSession:
      type: apiKey
      in: cookie
      name: flint_session
      description: Sealed WorkOS session required for claimed-Passport owner actions. Unclaimed mandate updates require the claim token as a management capability.
    PartnerServiceBearer:
      type: http
      scheme: bearer
      description: Server-only partner credential. The authenticated partner must match the partner in the stored signed verification record.
    X402Payment:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: Canonical x402 v2 payment proof on a paid retry. Initial unpaid challenge requests require no payment proof.
    FlintCapability:
      type: apiKey
      in: header
      name: FLINT-CAPABILITY
      description: Short-lived Passport-owner-issued capability bound to the exact x402 Verify request.
    DPoP:
      type: apiKey
      in: header
      name: DPoP
      description: Fresh caller proof bound to the capability, request, and x402 payment proof.
    X401Proof:
      type: apiKey
      in: header
      name: PROOF-RESPONSE
      description: Base64url-encoded x401 principal-identity presentation. Omit to request a proof challenge.
    bearerAgentSession:
      type: http
      scheme: bearer
      bearerFormat: flint_sess_...
      description: 'Agent session bearer token minted by POST /api/auth/otp-verify (Authorization: Bearer flint_sess_...). Accepted everywhere a WorkOSOwnerSession cookie is accepted, so an MCP agent never needs a browser. Also accepted via the X-FLINT-Session header.'