OpenAPI Specification
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>`.
'