{ "openapi": "3.1.0", "info": { "title": "Cedar Merchant API", "version": "0.0.0", "description": "Customer-facing REST API. API Client and API Key resources are Access projections." }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://api.usecedar.co" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Health" }, { "name": "API Clients" }, { "name": "API Keys" }, { "name": "Checkout Sessions" } ], "paths": { "/health": { "get": { "operationId": "getHealth", "tags": [ "Health" ], "summary": "Health", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } }, "/v1/api_clients": { "get": { "operationId": "listApiClients", "tags": [ "API Clients" ], "summary": "List API Clients for the authenticated Tenant", "responses": { "200": { "description": "API Clients, including revoked", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiClient" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "createApiClient", "tags": [ "API Clients" ], "summary": "Create an API Client", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiClientRequest" } } } }, "responses": { "200": { "description": "Created API Client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClient" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/api_clients/{api_client_id}": { "parameters": [ { "$ref": "#/components/parameters/ApiClientId" } ], "get": { "operationId": "getApiClient", "tags": [ "API Clients" ], "summary": "Get an API Client", "responses": { "200": { "description": "API Client, including revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClient" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateApiClient", "tags": [ "API Clients" ], "summary": "Update API Client roles", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiClientRequest" } } } }, "responses": { "200": { "description": "Updated API Client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClient" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "operationId": "revokeApiClient", "tags": [ "API Clients" ], "summary": "Revoke an API Client", "responses": { "200": { "description": "Revoked API Client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClient" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/api_clients/{api_client_id}/api_keys": { "parameters": [ { "$ref": "#/components/parameters/ApiClientId" } ], "get": { "operationId": "listApiKeys", "tags": [ "API Keys" ], "summary": "List API Keys for an API Client", "parameters": [ { "name": "environment", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ApiKeyEnvironment" } } ], "responses": { "200": { "description": "API Keys, including revoked", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "createApiKey", "tags": [ "API Keys" ], "summary": "Create an API Key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "200": { "description": "Issued API Key. Secret is returned once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedApiKey" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/api_clients/{api_client_id}/api_keys/{api_key_id}": { "parameters": [ { "$ref": "#/components/parameters/ApiClientId" }, { "$ref": "#/components/parameters/ApiKeyId" } ], "get": { "operationId": "getApiKey", "tags": [ "API Keys" ], "summary": "Get an API Key", "responses": { "200": { "description": "API Key, including revoked. Secret is not returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "revokeApiKey", "tags": [ "API Keys" ], "summary": "Revoke an API Key", "responses": { "200": { "description": "Revoked API Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/api_clients/{api_client_id}/api_keys/{api_key_id}/rotate": { "parameters": [ { "$ref": "#/components/parameters/ApiClientId" }, { "$ref": "#/components/parameters/ApiKeyId" } ], "post": { "operationId": "rotateApiKey", "tags": [ "API Keys" ], "summary": "Rotate an API Key secret", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateApiKeyRequest" } } } }, "responses": { "200": { "description": "Issued API Key. New secret is returned once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedApiKey" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/checkout_sessions": { "get": { "operationId": "listCheckoutSessions", "tags": [ "Checkout Sessions" ], "summary": "List Checkout Sessions for the authenticated Tenant", "responses": { "200": { "description": "Checkout Sessions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSession" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "createCheckoutSession", "tags": [ "Checkout Sessions" ], "summary": "Create a Checkout Session", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionRequest" } } } }, "responses": { "200": { "description": "Created Checkout Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/v1/checkout_sessions/{checkout_session_id}": { "parameters": [ { "$ref": "#/components/parameters/CheckoutSessionId" } ], "get": { "operationId": "getCheckoutSession", "tags": [ "Checkout Sessions" ], "summary": "Get a Checkout Session", "responses": { "200": { "description": "Checkout Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateCheckoutSession", "tags": [ "Checkout Sessions" ], "summary": "Update an open Checkout Session", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCheckoutSessionRequest" } } } }, "responses": { "200": { "description": "Updated Checkout Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/v1/checkout_sessions/{checkout_session_id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/CheckoutSessionId" } ], "post": { "operationId": "cancelCheckoutSession", "tags": [ "Checkout Sessions" ], "summary": "Cancel an open Checkout Session", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Canceled Checkout Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API Key secret. Authorization Bearer, not the apk_ public id." } }, "parameters": { "ApiClientId": { "name": "api_client_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApiClientId" } }, "ApiKeyId": { "name": "api_key_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ApiKeyId" } }, "CheckoutSessionId": { "name": "checkout_session_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/CheckoutSessionId" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Required on create, update, cancel, and pay writes. Same key and body after commit returns the first result; same key and different body returns UNPROCESSABLE." } }, "schemas": { "Health": { "type": "object", "additionalProperties": false, "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } }, "ApiClientId": { "type": "string", "pattern": "^apc_[A-Za-z0-9]+$" }, "ApiKeyId": { "type": "string", "pattern": "^apk_[A-Za-z0-9]+$" }, "ApiKeyEnvironment": { "type": "string", "enum": [ "test", "live" ] }, "ApiClientRoles": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "admin", "developer", "finance", "viewer" ] } }, "ApiClient": { "type": "object", "additionalProperties": false, "required": [ "id", "tenant_id", "roles", "revoked_at" ], "properties": { "id": { "$ref": "#/components/schemas/ApiClientId" }, "tenant_id": { "type": "string" }, "roles": { "$ref": "#/components/schemas/ApiClientRoles" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ApiKey": { "type": "object", "additionalProperties": false, "required": [ "id", "api_client_id", "expires_at", "revoked_at", "environment" ], "properties": { "id": { "$ref": "#/components/schemas/ApiKeyId" }, "api_client_id": { "$ref": "#/components/schemas/ApiClientId" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "environment": { "$ref": "#/components/schemas/ApiKeyEnvironment" } } }, "IssuedApiKey": { "type": "object", "additionalProperties": false, "required": [ "api_key", "secret" ], "properties": { "api_key": { "$ref": "#/components/schemas/ApiKey" }, "secret": { "type": "string", "pattern": "^ask_(test|live)_[0-9a-f]{64}$" } } }, "CreateApiClientRequest": { "type": "object", "additionalProperties": false, "required": [ "roles" ], "properties": { "roles": { "$ref": "#/components/schemas/ApiClientRoles" } } }, "UpdateApiClientRequest": { "type": "object", "additionalProperties": false, "required": [ "roles" ], "properties": { "roles": { "$ref": "#/components/schemas/ApiClientRoles" } } }, "CreateApiKeyRequest": { "type": "object", "additionalProperties": false, "required": [ "environment" ], "properties": { "environment": { "$ref": "#/components/schemas/ApiKeyEnvironment" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "RotateApiKeyRequest": { "type": "object", "additionalProperties": false, "properties": { "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CheckoutSessionId": { "type": "string", "pattern": "^cs_[A-Za-z0-9]+$" }, "CheckoutSessionStatus": { "type": "string", "enum": [ "open", "completed", "expired", "canceled" ] }, "CheckoutSessionLineItem": { "type": "object", "additionalProperties": false, "required": [ "name", "quantity", "unit_amount", "currency" ], "properties": { "name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "unit_amount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" }, "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } }, "CheckoutSession": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "line_items", "tax_amount", "shipping_amount", "discount_amount", "amount_subtotal", "amount_total", "currency", "customer_email", "expires_at", "pay_url", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/CheckoutSessionId" }, "status": { "$ref": "#/components/schemas/CheckoutSessionStatus" }, "line_items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/CheckoutSessionLineItem" } }, "tax_amount": { "type": "integer", "minimum": 0 }, "shipping_amount": { "type": "integer", "minimum": 0 }, "discount_amount": { "type": "integer", "minimum": 0 }, "amount_subtotal": { "type": "integer", "minimum": 0 }, "amount_total": { "type": "integer" }, "currency": { "type": "string" }, "customer_email": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "format": "date-time" }, "pay_url": { "type": "string", "format": "uri", "description": "Cedar-hosted pay page URL with opaque pay capability token (not raw cs_ id)." }, "success_url": { "type": [ "string", "null" ], "format": "uri" }, "cancel_url": { "type": [ "string", "null" ], "format": "uri" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateCheckoutSessionRequest": { "type": "object", "additionalProperties": false, "required": [ "line_items", "currency" ], "properties": { "line_items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/CheckoutSessionLineItem" } }, "currency": { "type": "string" }, "tax_amount": { "type": "integer", "minimum": 0 }, "shipping_amount": { "type": "integer", "minimum": 0 }, "discount_amount": { "type": "integer", "minimum": 0 }, "customer_email": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "success_url": { "type": "string", "format": "uri" }, "cancel_url": { "type": "string", "format": "uri" } } }, "UpdateCheckoutSessionRequest": { "type": "object", "additionalProperties": false, "properties": { "line_items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/CheckoutSessionLineItem" } }, "tax_amount": { "type": "integer", "minimum": 0 }, "shipping_amount": { "type": "integer", "minimum": 0 }, "discount_amount": { "type": "integer", "minimum": 0 }, "customer_email": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } }, "Error": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND", "CONFLICT", "INVALID_REQUEST", "EXPIRED", "REVOKED", "UNAUTHORIZED", "FORBIDDEN", "UNPROCESSABLE", "OWNER_MISMATCH" ] } } } }, "responses": { "InvalidRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or unusable Bearer secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Principal Roles cannot perform this act", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Unknown id, or path client/key mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Revoked or expired resource, or conflicting write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unprocessable": { "description": "Expired session, wrong state, idempotency body mismatch, or concurrent pay conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }