{
  "components": {
    "schemas": {
      "AccessItem": {
        "additionalProperties": false,
        "description": "One version a batch asks for.",
        "properties": {
          "secret_id": {
            "format": "uuid",
            "type": "string"
          },
          "version": {
            "format": "int32",
            "type": "integer"
          }
        },
        "required": [
          "secret_id",
          "version"
        ],
        "type": "object"
      },
      "AccessResult": {
        "description": "One opened version, or the code that says why it was not opened.",
        "properties": {
          "code": {
            "type": [
              "string",
              "null"
            ]
          },
          "secret_id": {
            "format": "uuid",
            "type": "string"
          },
          "value": {
            "type": [
              "string",
              "null"
            ]
          },
          "version": {
            "format": "int32",
            "type": "integer"
          }
        },
        "required": [
          "secret_id",
          "version"
        ],
        "type": "object"
      },
      "B64": {
        "description": "base64url without padding",
        "format": "byte",
        "type": "string"
      },
      "BatchAccess": {
        "additionalProperties": false,
        "description": "`POST /v1/secrets/versions:batchAccess` body.",
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/AccessItem"
            },
            "type": "array"
          }
        },
        "required": [
          "items"
        ],
        "type": "object"
      },
      "BatchAccessResult": {
        "description": "`POST /v1/secrets/versions:batchAccess` response, in request order.",
        "properties": {
          "results": {
            "items": {
              "$ref": "#/components/schemas/AccessResult"
            },
            "type": "array"
          }
        },
        "required": [
          "results"
        ],
        "type": "object"
      },
      "BatchGet": {
        "properties": {
          "refs": {
            "items": {
              "$ref": "#/components/schemas/SecretRef"
            },
            "type": "array"
          }
        },
        "required": [
          "refs"
        ],
        "type": "object"
      },
      "BatchGetResult": {
        "properties": {
          "results": {
            "items": {
              "$ref": "#/components/schemas/SealedResult"
            },
            "type": "array"
          }
        },
        "required": [
          "results"
        ],
        "type": "object"
      },
      "CacheHint": {
        "description": "Cache hints the server sends with each value.",
        "properties": {
          "max_age": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "stale_while_revalidate": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "max_age",
          "stale_while_revalidate"
        ],
        "type": "object"
      },
      "EncryptionMode": {
        "description": "`zk` or `managed` (SEC-05).",
        "enum": [
          "zk",
          "managed"
        ],
        "type": "string"
      },
      "EnvironmentSecrets": {
        "properties": {
          "cache": {
            "$ref": "#/components/schemas/CacheHint"
          },
          "environment_id": {
            "format": "uuid",
            "type": "string"
          },
          "environment_revision": {
            "format": "int64",
            "type": "integer"
          },
          "project_id": {
            "format": "uuid",
            "type": "string"
          },
          "secrets": {
            "items": {
              "$ref": "#/components/schemas/ListedSecret"
            },
            "type": "array"
          }
        },
        "required": [
          "environment_id",
          "project_id",
          "environment_revision",
          "secrets",
          "cache"
        ],
        "type": "object"
      },
      "ListedSecret": {
        "description": "One secret in an environment listing on `secrets-api`. Carries `meta_ct` so the client can\nrecover names, which `sphragis run` needs for environment variable names.",
        "properties": {
          "dek_wrapped": {
            "$ref": "#/components/schemas/B64"
          },
          "env_key_version": {
            "format": "int32",
            "type": "integer"
          },
          "lookup": {
            "$ref": "#/components/schemas/B64"
          },
          "meta_ct": {
            "$ref": "#/components/schemas/B64"
          },
          "path": {
            "type": [
              "string",
              "null"
            ]
          },
          "secret_id": {
            "format": "uuid",
            "type": "string"
          },
          "value": {
            "description": "The value in clear. Managed projects only.",
            "type": [
              "string",
              "null"
            ]
          },
          "value_ct": {
            "$ref": "#/components/schemas/B64"
          },
          "version": {
            "format": "int32",
            "type": "integer"
          }
        },
        "required": [
          "secret_id",
          "lookup",
          "meta_ct",
          "version"
        ],
        "type": "object"
      },
      "MachineGrant": {
        "description": "One environment key grant to the machine identity.",
        "properties": {
          "encryption_mode": {
            "$ref": "#/components/schemas/EncryptionMode"
          },
          "env_key_wrapped": {
            "$ref": "#/components/schemas/B64"
          },
          "environment": {
            "description": "`project_slug.env_slug`.",
            "type": "string"
          },
          "environment_id": {
            "format": "uuid",
            "type": "string"
          },
          "granted_by": {
            "format": "uuid",
            "type": [
              "string",
              "null"
            ]
          },
          "granter_sign_public_key": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/B64"
              },
              {
                "type": "null"
              }
            ]
          },
          "key_version": {
            "format": "int32",
            "type": "integer"
          },
          "project_id": {
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "environment_id",
          "project_id",
          "environment",
          "encryption_mode",
          "key_version",
          "env_key_wrapped"
        ],
        "type": "object"
      },
      "MachineIdentity": {
        "description": "`GET /v1/identity` on `secrets-api`.",
        "properties": {
          "account_id": {
            "format": "uuid",
            "type": "string"
          },
          "grants": {
            "items": {
              "$ref": "#/components/schemas/MachineGrant"
            },
            "type": "array"
          },
          "identity_id": {
            "format": "uuid",
            "type": "string"
          },
          "identity_key_wrapped": {
            "$ref": "#/components/schemas/B64"
          },
          "plan": {
            "type": "string"
          },
          "token_id": {
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "identity_id",
          "account_id",
          "token_id",
          "identity_key_wrapped",
          "grants",
          "plan"
        ],
        "type": "object"
      },
      "RevisionChange": {
        "description": "A revision change pushed over the watch stream.",
        "properties": {
          "environment_id": {
            "format": "uuid",
            "type": "string"
          },
          "revision": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "environment_id",
          "revision"
        ],
        "type": "object"
      },
      "SealedResult": {
        "description": "One result. On success the sealed fields are set, or `value` for Managed projects. On failure\n`code` names the reason.",
        "properties": {
          "cache": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/CacheHint"
              },
              {
                "type": "null"
              }
            ]
          },
          "code": {
            "type": [
              "string",
              "null"
            ]
          },
          "dek_wrapped": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/B64"
              },
              {
                "type": "null"
              }
            ]
          },
          "env_key_version": {
            "format": "int32",
            "type": [
              "integer",
              "null"
            ]
          },
          "environment_id": {
            "format": "uuid",
            "type": [
              "string",
              "null"
            ]
          },
          "environment_revision": {
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "expires_at": {
            "description": "When this version expires (SEC-09).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "ok": {
            "type": "boolean"
          },
          "secret_id": {
            "format": "uuid",
            "type": [
              "string",
              "null"
            ]
          },
          "value": {
            "description": "The value in clear. Managed projects only, in place of the sealed fields.",
            "type": [
              "string",
              "null"
            ]
          },
          "value_ct": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/B64"
              },
              {
                "type": "null"
              }
            ]
          },
          "version": {
            "format": "int32",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "ok"
        ],
        "type": "object"
      },
      "SecretRef": {
        "description": "One reference in a batch read.",
        "properties": {
          "environment": {
            "description": "An environment id or `project_slug.env_slug`.",
            "type": "string"
          },
          "lookup": {
            "description": "The lookup HMAC (Zero-knowledge) or the path (Managed), base64url for both.",
            "type": "string"
          },
          "version": {
            "description": "`latest`, an alias or a version number.",
            "type": "string"
          }
        },
        "required": [
          "environment",
          "lookup"
        ],
        "type": "object"
      },
      "TokenExchange": {
        "description": "The answer to an RFC 8693 token exchange on `POST /v1/auth/token`.",
        "properties": {
          "access_token": {
            "type": "string"
          },
          "expires_in": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "issued_token_type": {
            "type": "string"
          },
          "token_type": {
            "type": "string"
          }
        },
        "required": [
          "access_token",
          "issued_token_type",
          "token_type",
          "expires_in"
        ],
        "type": "object"
      },
      "VersionValue": {
        "description": "The value of one version. Zero-knowledge projects return it sealed. Managed projects return\n`value` in clear and leave the sealed fields empty.",
        "properties": {
          "dek_wrapped": {
            "$ref": "#/components/schemas/B64"
          },
          "env_key_version": {
            "format": "int32",
            "type": "integer"
          },
          "environment_revision": {
            "format": "int64",
            "type": "integer"
          },
          "expires_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "secret_id": {
            "format": "uuid",
            "type": "string"
          },
          "value": {
            "type": [
              "string",
              "null"
            ]
          },
          "value_ct": {
            "$ref": "#/components/schemas/B64"
          },
          "version": {
            "format": "int32",
            "type": "integer"
          }
        },
        "required": [
          "secret_id",
          "version",
          "environment_revision"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "dpop_session": {
        "description": "`DPoP sps_…` plus a `DPoP` proof whose `htu` names this service (API.md §3.1)",
        "in": "header",
        "name": "Authorization",
        "type": "apiKey"
      },
      "machine_token": {
        "bearerFormat": "sph_mi_<id>.<key>",
        "description": "The workload half of a machine token (API.md §3.2). The token secret never leaves the workload.",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Read path for machine identities. Values arrive sealed and decrypt in the client library.",
    "license": {
      "identifier": "LicenseRef-Sphragis",
      "name": "LicenseRef-Sphragis"
    },
    "title": "Sphragis Secrets read API",
    "version": "0.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/v1/auth/token": {
      "post": {
        "operationId": "token",
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "string"
              }
            }
          },
          "description": "grant_type, subject_token, subject_token_type and audience=sphragis:identity:<id>",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenExchange"
                }
              }
            },
            "description": "A short-lived access token"
          },
          "401": {
            "description": "No trust policy accepts the token"
          },
          "422": {
            "description": "Malformed request"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "security": [],
        "summary": "RFC 8693 token exchange (API.md §3.3).",
        "tags": [
          "read"
        ]
      }
    },
    "/v1/environments/{e}/secrets": {
      "get": {
        "operationId": "list",
        "parameters": [
          {
            "description": "Environment id",
            "in": "path",
            "name": "e",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Ignored in Zero-knowledge mode",
            "in": "query",
            "name": "prefix",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvironmentSecrets"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "description": "Not found"
          }
        },
        "security": [
          {
            "machine_token": []
          }
        ],
        "summary": "Every readable secret in an environment, for `sphragis run` and `sphragis export`.",
        "tags": [
          "read"
        ]
      }
    },
    "/v1/environments/{e}/secrets/{lookup}/versions/{v}": {
      "get": {
        "operationId": "get_version",
        "parameters": [
          {
            "description": "Environment id",
            "in": "path",
            "name": "e",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Blind index of the path, base64url",
            "in": "path",
            "name": "lookup",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A number, an alias or latest",
            "in": "path",
            "name": "v",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SealedResult"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Version disabled"
          },
          "410": {
            "description": "Version destroyed"
          }
        },
        "security": [
          {
            "machine_token": []
          }
        ],
        "summary": "One version. `v` is a number, an alias or `latest`.",
        "tags": [
          "read"
        ]
      }
    },
    "/v1/environments/{e}/watch": {
      "get": {
        "operationId": "watch",
        "parameters": [
          {
            "description": "Environment id",
            "in": "path",
            "name": "e",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Last revision seen",
            "in": "query",
            "name": "since",
            "required": false,
            "schema": {
              "format": "int64",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/event-stream": {}
            },
            "description": "Server-sent `revision` events carrying a RevisionChange"
          }
        },
        "security": [
          {
            "machine_token": []
          }
        ],
        "summary": "Server-sent events on revision change. The stream ends after an hour so connections rebalance.",
        "tags": [
          "read"
        ]
      }
    },
    "/v1/healthz": {
      "get": {
        "operationId": "healthz",
        "responses": {
          "200": {
            "description": "Alive"
          }
        },
        "security": [],
        "summary": "Liveness.",
        "tags": [
          "ops"
        ]
      }
    },
    "/v1/identity": {
      "get": {
        "operationId": "identity",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MachineIdentity"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "description": "Missing or revoked token"
          }
        },
        "security": [
          {
            "machine_token": []
          }
        ],
        "summary": "Who am I: the wrapped identity seed and the environment key grants (§3.2).",
        "tags": [
          "read"
        ]
      }
    },
    "/v1/readyz": {
      "get": {
        "operationId": "readyz",
        "responses": {
          "200": {
            "description": "Ready"
          },
          "503": {
            "description": "Not ready"
          }
        },
        "security": [],
        "summary": "Readiness: the database answers.",
        "tags": [
          "ops"
        ]
      }
    },
    "/v1/secrets/secrets/{s}/versions/{v}": {
      "get": {
        "description": "# Errors\n`not_found`, `iam.permission_denied`, `secrets.not_managed` for a Zero-knowledge project,\n`secrets.version_disabled`, `secrets.version_destroyed`, and `unavailable` when `keyd`\ncannot be reached.",
        "operationId": "person_get_version",
        "parameters": [
          {
            "in": "path",
            "name": "s",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "description": "A number, an alias or latest",
            "in": "path",
            "name": "v",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionValue"
                }
              }
            },
            "description": "OK"
          },
          "409": {
            "description": "Disabled"
          },
          "410": {
            "description": "Destroyed"
          },
          "422": {
            "description": "Not a Managed project"
          }
        },
        "security": [
          {
            "dpop_session": []
          }
        ],
        "summary": "A Managed version in clear, for a person (`GET /v1/secrets/secrets/{s}/versions/{v}`). `v` is\na number, an alias or `latest`. The read is audited.",
        "tags": [
          "person"
        ]
      }
    },
    "/v1/secrets/versions:batchAccess": {
      "post": {
        "description": "# Errors\n`validation.failed` for an empty or oversized batch, `unavailable` when `keyd` cannot be\nreached. Nothing is returned or recorded unless every open succeeds.",
        "operationId": "person_batch_access",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchAccess"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchAccessResult"
                }
              }
            },
            "description": "OK"
          }
        },
        "security": [
          {
            "dpop_session": []
          }
        ],
        "summary": "Opens many Managed versions for a person (`POST /v1/secrets/versions:batchAccess`). A\nrollback uses it to read the versions it restores. Each opened version is audited. A version\nthat cannot be opened carries its code and the others still open.",
        "tags": [
          "person"
        ]
      }
    },
    "/v1/secrets:batchGet": {
      "post": {
        "operationId": "batch_get",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchGet"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchGetResult"
                }
              }
            },
            "description": "OK"
          },
          "422": {
            "description": "Between 1 and 100 references"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "security": [
          {
            "machine_token": []
          }
        ],
        "summary": "Up to 100 references in one call.",
        "tags": [
          "read"
        ]
      }
    }
  },
  "servers": [
    {
      "url": "https://secrets.sphragis.siliconblast.com"
    }
  ],
  "tags": [
    {
      "description": "Secret reads with a machine token",
      "name": "read"
    },
    {
      "description": "Managed reads by a person with a DPoP-bound session",
      "name": "person"
    },
    {
      "description": "Health",
      "name": "ops"
    }
  ]
}