{ "openapi": "3.1.0", "info": { "title": "zpe repo access", "version": "2.0.0", "description": "Sell access to a private GitHub repo on the seller's own payment key: a buyer pays, the engine puts them in the seller's org team, and a refund takes them out. Every operation lives under the versioned base `/_/api/v1`, and this document is served at `/_/api/v1/openapi.json`. Every operation is scoped to the authenticated account: the only tenant a caller can name is its own. Authenticate with the door's session cookie or with a token minted at `POST /_/api/v1/tokens`." }, "servers": [ { "url": "/repo-access", "description": "zpe-repo-access on zpe.vc" } ], "paths": { "/_/api/v1/tenants": { "get": { "operationId": "getTenants", "summary": "The caller's tenant, the names of its stored credentials, and how the call authenticated", "tags": [ "tenants" ], "responses": { "200": { "description": "The caller's tenant, or `null` before one exists; the names of its stored credentials; and how the call authenticated (`session` or `token`).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "The credential is missing or does not open this account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "This account may not do that: the credential's grant does not name this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests: this caller has spent its request ceiling, and `Retry-After` says when to come back", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "This app failed while answering", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A service this app needs did not answer — the door could not be reached, so this request was not checked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "operationId": "putTenants", "summary": "Create or update the caller's tenant: its label, org, product-to-team map and branding", "tags": [ "tenants" ], "responses": { "200": { "description": "The tenant as saved, with the webhook address the engine calls for this seller's payments.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The body was not a JSON object, so there was no tenant to write.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The credential is missing or does not open this account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "This account may not do that: the credential's grant does not name this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "That GitHub org already belongs to another tenant on this deployment; one org cannot be sold from twice.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`org`, `product_team_map` or `branding` did not pass the vendored guard: an org is `owner/name`, and the map and branding are objects.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests: this caller has spent its request ceiling, and `Retry-After` says when to come back", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "This app failed while answering", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A service this app needs did not answer — the door could not be reached, so this request was not checked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "operationId": "postTenants", "summary": "Create or update the caller's tenant (the same write as PUT)", "tags": [ "tenants" ], "responses": { "200": { "description": "The tenant as saved, with the webhook address the engine calls for this seller's payments.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The body was not a JSON object, so there was no tenant to write.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The credential is missing or does not open this account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "This account may not do that: the credential's grant does not name this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "That GitHub org already belongs to another tenant on this deployment; one org cannot be sold from twice.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`org`, `product_team_map` or `branding` did not pass the vendored guard: an org is `owner/name`, and the map and branding are objects.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests: this caller has spent its request ceiling, and `Retry-After` says when to come back", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "This app failed while answering", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A service this app needs did not answer — the door could not be reached, so this request was not checked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "operationId": "deleteTenants", "summary": "Revoke the tenant: remove its buyers from the org, expire its claims, drop its credentials", "tags": [ "tenants" ], "responses": { "200": { "description": "The tenant is revoked: its claims expired, its stored credentials dropped and its queued jobs cancelled. The counts say what moved.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "The credential is missing or does not open this account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "This account may not do that: the credential's grant does not name this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests: this caller has spent its request ceiling, and `Retry-After` says when to come back", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "This app failed while answering", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A service this app needs did not answer — the door could not be reached, so this request was not checked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/_/api/v1/tenants/secrets": { "get": { "operationId": "getTenantsSecrets", "summary": "The names of the tenant's stored credentials, never their values", "tags": [ "tenants" ], "responses": { "200": { "description": "The names of the tenant's stored credentials. No call returns a value.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "The credential is missing or does not open this account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "This account may not do that: the credential's grant does not name this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests: this caller has spent its request ceiling, and `Retry-After` says when to come back", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "This app failed while answering", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A service this app needs did not answer — the door could not be reached, so this request was not checked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/_/api/v1/tenants/secrets/{name}": { "put": { "operationId": "putTenantsSecretsById", "summary": "Store one credential (payment_webhook_secret or github_token), sealed under the tenant's key", "tags": [ "tenants" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The credential is stored and sealed under the tenant's key; the answer repeats every stored name.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "The credential is missing or does not open this account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "This account may not do that: the credential's grant does not name this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`name` is not `payment_webhook_secret` or `github_token`, or `value` is missing or blank.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests: this caller has spent its request ceiling, and `Retry-After` says when to come back", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "This app failed while answering", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The tenant's sealing key or the door did not answer, so nothing was stored.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/_/api/v1/tenants/purchases": { "get": { "operationId": "getTenantsPurchases", "summary": "The account's 100 most recently updated purchases", "tags": [ "tenants" ], "responses": { "200": { "description": "Up to 100 of the account's purchases, most recently updated first.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "The credential is missing or does not open this account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "This account may not do that: the credential's grant does not name this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests: this caller has spent its request ceiling, and `Retry-After` says when to come back", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "This app failed while answering", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A service this app needs did not answer — the door could not be reached, so this request was not checked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/_/api/v1/tenants/events": { "get": { "operationId": "getTenantsEvents", "summary": "The account's 100 most recent engine events", "tags": [ "tenants" ], "responses": { "200": { "description": "Up to 100 of the account's engine events, most recent first, each with an ISO timestamp.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "The credential is missing or does not open this account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "This account may not do that: the credential's grant does not name this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests: this caller has spent its request ceiling, and `Retry-After` says when to come back", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "This app failed while answering", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A service this app needs did not answer — the door could not be reached, so this request was not checked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/_/api/v1/tenants/reconcile": { "post": { "operationId": "postTenantsReconcile", "summary": "Re-assert every grant the tenant should hold against GitHub, and report what changed", "tags": [ "tenants" ], "responses": { "200": { "description": "Every grant the tenant should hold was re-asserted against GitHub; the report says what changed.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "The credential is missing or does not open this account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "This account may not do that: the credential's grant does not name this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "The caller has no tenant yet, so there is nothing to reconcile.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests: this caller has spent its request ceiling, and `Retry-After` says when to come back", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "This app failed while answering", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A service this app needs did not answer — the door could not be reached, so this request was not checked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/_/api/v1/tenants/sweep": { "post": { "operationId": "postTenantsSweep", "summary": "Run the queue sweep now: retry what is due, expire stale claim links", "tags": [ "tenants" ], "responses": { "200": { "description": "What the sweep retried, and how many stale claim links it expired. Counts only.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "The credential is missing or does not open this account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "This account may not do that: the credential's grant does not name this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests: this caller has spent its request ceiling, and `Retry-After` says when to come back", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "This app failed while answering", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A service this app needs did not answer — the door could not be reached, so this request was not checked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/_/api/v1/tokens": { "get": { "operationId": "getTokens", "summary": "The account's API tokens: id, label and dates, never the token", "tags": [ "tokens" ], "responses": { "200": { "description": "The account's tokens by id, label and dates. The token itself is never returned.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "The credential is missing or does not open this account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "This account may not do that: the credential's grant does not name this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests: this caller has spent its request ceiling, and `Retry-After` says when to come back", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "This app failed while answering", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A service this app needs did not answer — the door could not be reached, so this request was not checked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "operationId": "postTokens", "summary": "Mint an API token. It is shown once, in this answer, and never again", "tags": [ "tokens" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A retry handle: a second POST carrying the same value answers `200` with the first call's token id and label, `token: null`, and mints nothing.", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "A replay: this `Idempotency-Key` was already answered. The token id, label and date the first call returned, with `token: null`, and nothing minted.", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "A new token, shown once in this answer and never again.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The `Idempotency-Key` was sent empty or longer than 200 characters: a retry is found by that value, so a blank or oversized one names nothing and is refused rather than read as absent.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The credential is missing or does not open this account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "This account may not do that: the credential's grant does not name this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A live token already uses that label, or the store refused the write.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests: this caller has spent its request ceiling, and `Retry-After` says when to come back", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "This app failed while answering", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The deployment has no token pepper or no store, so no token was minted; or the door did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/_/api/v1/tokens/{id}": { "delete": { "operationId": "deleteTokensById", "summary": "Revoke an API token by id", "tags": [ "tokens" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The token is revoked. A caller presenting it is refused from now on.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "The credential is missing or does not open this account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "This account may not do that: the credential's grant does not name this app", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No live token with that id belongs to this account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests: this caller has spent its request ceiling, and `Retry-After` says when to come back", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "This app failed while answering", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A service this app needs did not answer — the door could not be reached, so this request was not checked", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key minted on the account's settings page at zpe.vc/home/settings. Send it as `Authorization: Bearer `." } }, "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem+json: `type`, `title`, `status`, `code` and `instance`, plus `detail` when a person should read a sentence.", "required": [ "type", "title", "status", "code", "instance" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string", "enum": [ "bad-request", "unauthenticated", "malformed", "unknown", "mismatch", "revoked", "expired", "another-account", "scope-refused", "grant-refused", "forbidden", "not-found", "method-not-allowed", "conflict", "gone", "payload-too-large", "unsupported-media-type", "unprocessable", "rate-limited", "payment-required", "not-open", "internal", "unavailable" ] }, "instance": { "type": "string" }, "detail": { "type": "string" } } } } }, "x-surface": { "app": "zpe-repo-access", "base": "/_/api/v1", "document": "/_/api/v1/openapi.json", "generated_by": "zpe-kit machineDocument" }, "x-zpe-routes": 13, "x-zpe-documented": 13, "x-zpe-internal": [] }