openapi: 3.0.3
info:
  title: Ava Protocol AVS Auth Secrets API
  version: 1.0.0
  description: 'Public REST API for the Ava Protocol AVS aggregator. Exposes workflow

    creation, execution monitoring, smart-wallet management, and related

    operations.


    Authentication is a single credential type — a JWT bearer token — obtained

    either via the wallet-signing flow (`POST /auth:exchange`) or out-of-band

    via the operator-run `create-api-key` CLI. Every request must include

    `Authorization: Bearer <jwt>`.

    '
servers:
- url: https://gateway.avaprotocol.org/api/v1
  description: Production gateway
- url: https://gateway-staging.avaprotocol.org/api/v1
  description: Staging gateway
- url: http://localhost:8080/api/v1
  description: Local dev
security:
- bearerAuth: []
tags:
- name: Secrets
  description: User/workflow/org secret storage
paths:
  /secrets:
    get:
      tags:
      - Secrets
      summary: List secrets (metadata only — values are never echoed)
      operationId: listSecrets
      parameters:
      - name: workflowId
        in: query
        schema:
          $ref: '#/components/schemas/Ulid'
      - name: orgId
        in: query
        schema:
          type: string
      - $ref: '#/components/parameters/PageBefore'
      - $ref: '#/components/parameters/PageAfter'
      - $ref: '#/components/parameters/PageLimit'
      responses:
        '200':
          description: Page of secret metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /secrets/{name}:
    parameters:
    - name: name
      in: path
      required: true
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_]+$
    put:
      tags:
      - Secrets
      summary: Create or replace a secret (idempotent)
      operationId: putSecret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutSecretRequest'
      responses:
        '201':
          description: Secret created.
        '204':
          description: Secret replaced (already existed).
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      tags:
      - Secrets
      summary: Delete a secret
      operationId: deleteSecret
      parameters:
      - name: workflowId
        in: query
        schema:
          $ref: '#/components/schemas/Ulid'
      - name: orgId
        in: query
        schema:
          type: string
      responses:
        '204':
          description: Secret deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Ulid:
      type: string
      pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
      description: ULID identifier (26-char Crockford base32).
      example: 01JG2FE5MDVKBPHEG0PEYSDKAC
    PageInfo:
      type: object
      required:
      - hasNextPage
      - hasPreviousPage
      properties:
        hasNextPage:
          type: boolean
        hasPreviousPage:
          type: boolean
        startCursor:
          type: string
          description: Cursor for the first item in the current page; pass to `before` for the previous page.
        endCursor:
          type: string
          description: Cursor for the last item in the current page; pass to `after` for the next page.
    SecretList:
      type: object
      required:
      - data
      - pageInfo
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Secret'
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
    Problem:
      type: object
      description: 'RFC 7807 problem+json. Returned as `application/problem+json` on any

        4xx/5xx response. `type` and `title` describe the error class; `detail`

        is human-readable; `instance` is a per-request identifier suitable for

        log correlation.

        '
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
          format: uri
          description: URI identifying the problem type.
          example: https://docs.avaprotocol.org/errors/workflow-not-found
        title:
          type: string
          description: Short, human-readable summary.
          example: Workflow not found
        status:
          type: integer
          format: int32
          description: HTTP status code (echoed for clients that surface only the body).
          example: 404
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
          example: No workflow with id 01JG2FE5MDVKBPHEG0PEYSDKAC for owner 0xabc...
        instance:
          type: string
          description: URI / opaque ID identifying this specific occurrence (e.g., request id).
          example: req_01JG2FE5MFKTH0754RGF2DMVY7
        code:
          type: string
          description: 'Machine-readable error code. Stable across releases; clients can

            switch on this for programmatic handling. Mirrors the gRPC-era

            ErrorCode enum vocabulary.

            '
          example: WORKFLOW_NOT_FOUND
    PutSecretRequest:
      type: object
      required:
      - value
      properties:
        value:
          type: string
          description: Secret value (write-only, never echoed back).
        workflowId:
          $ref: '#/components/schemas/Ulid'
        orgId:
          type: string
    Secret:
      type: object
      description: 'Stored secret. The `value` is write-only — list/get responses

        return metadata only, never the secret value.

        '
      required:
      - name
      - scope
      properties:
        name:
          type: string
        scope:
          type: string
          enum:
          - user
          - workflow
          - org
          description: 'Scope determines visibility — `user` = available to all the

            user''s workflows; `workflow` = scoped to one workflow id;

            `org` = scoped to an org id.

            '
        workflowId:
          $ref: '#/components/schemas/Ulid'
        orgId:
          type: string
        createdAt:
          type: integer
          format: int64
        updatedAt:
          type: integer
          format: int64
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: Resource not found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    BadRequest:
      description: Request validation failed.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  parameters:
    PageAfter:
      name: after
      in: query
      description: Cursor — return items immediately after this position (forward pagination).
      schema:
        type: string
    PageBefore:
      name: before
      in: query
      description: Cursor — return items immediately before this position (backward pagination).
      schema:
        type: string
    PageLimit:
      name: limit
      in: query
      description: Max items to return. Default 20; server-enforced ceiling applies.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 200
        default: 20
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT bearer token. Obtained via `POST /auth:exchange` (wallet

        signature flow) or via the operator-run `create-api-key` CLI

        (long-lived, server-to-server). Send on every request as

        `Authorization: Bearer <jwt>`.

        '