{"openapi":"3.1.0","info":{"title":"Example Next.js Resource Server API","version":"0.5.3","description":"Demo API of the SchemaVaults example resource server. Every operation is declared with @schemavaults/openapi-operations; this document and the /docs pages are generated from those declarations."},"servers":[{"url":"https://example-nextjs-resource-server.schemavaults.com","description":"This resource server"}],"tags":[{"name":"Demo","description":"Unauthenticated operations showing validation and the error envelope"},{"name":"Account","description":"Operations available to any signed-in SchemaVaults user"},{"name":"Admin","description":"Operations restricted to platform administrators"},{"name":"Organizations","description":"Operations gated on organization membership"}],"components":{"securitySchemes":{"schemavaults-access-token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Access token issued by the SchemaVaults auth server for this API server.","x-schemavaults-title":"SchemaVaults access token (Bearer)","x-schemavaults-challenge":"Bearer realm=\"schemavaults\""},"schemavaults-access-token-cookie":{"type":"apiKey","in":"cookie","name":"access_token_<api_server_id>","description":"First-party access token cookie set by the SchemaVaults auth flow.","x-schemavaults-title":"SchemaVaults access token (cookie)"}},"schemas":{"EchoResponse":{"type":"object","properties":{"echoes":{"type":"array","items":{"type":"string"}}},"required":["echoes"]},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","example":"unauthorized"},"message":{"type":"string"}},"required":["success","error","message"],"description":"Error envelope used by every non-2xx response"},"EchoRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":280,"example":"hello"},"repeat":{"type":"integer","minimum":1,"maximum":5,"default":1,"description":"How many times to repeat the message (1-5)"}},"required":["message"]},"Whoami":{"type":"object","properties":{"uid":{"type":"string","description":"SchemaVaults user id"},"email":{"type":["string","null"]},"admin":{"type":"boolean"},"scheme":{"type":"string","description":"Name of the auth scheme that resolved the credential","example":"schemavaults-access-token"},"scope":{"type":["string","null"],"description":"Space separated scope granted to the token, or null when it carries no scope claim"}},"required":["uid","email","admin","scheme","scope"]}},"parameters":{}},"paths":{"/api/health":{"get":{"operationId":"get_api_health","summary":"Liveness probe","description":"Unauthenticated health check. Reports the app environment the server runs in.","tags":["Demo"],"security":[],"x-schemavaults-auth":{"public":true,"schemes":[],"routeGuard":null,"requiredScopes":[],"organization":null,"notes":"Anyone can call this; it is what load balancers poll."},"responses":{"200":{"description":"The server is up","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"environment":{"type":"string","enum":["development","test","staging","production"]},"timestamp":{"type":"integer","description":"Unix epoch milliseconds when the response was produced","example":1757000000000}},"required":["ok","environment","timestamp"]}}}}}}},"/api/echo":{"post":{"operationId":"post_api_echo","summary":"Echo a message","description":"Demonstrates JSON body validation: the body is parsed with the declared zod schema and a 400 with per-field issues is returned when it does not match.","tags":["Demo"],"security":[],"x-schemavaults-auth":{"public":true,"schemes":[],"routeGuard":null,"requiredScopes":[],"organization":null},"requestBody":{"required":true,"description":"Message to echo back","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EchoRequest"}}}},"responses":{"200":{"description":"The echoed message(s)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EchoResponse"}}}},"400":{"description":"The body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/ping":{"post":{"operationId":"post_api_ping","summary":"Authenticated ping","description":"Returns a pong for any signed-in user. Accepts the access token either as a Bearer header (what the account page's test button sends) or as the first-party access token cookie.","tags":["Account"],"security":[{"schemavaults-access-token":[]},{"schemavaults-access-token-cookie":[]}],"x-schemavaults-auth":{"public":false,"schemes":["schemavaults-access-token","schemavaults-access-token-cookie"],"routeGuard":"authenticated","requiredScopes":[],"organization":null},"responses":{"200":{"description":"Pong","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","enum":["Pong!"]},"timestamp":{"type":"integer","description":"Unix epoch milliseconds when the response was produced","example":1757000000000}},"required":["message","timestamp"]}}}},"401":{"description":"No valid SchemaVaults credential was presented","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential is valid but not allowed to perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/whoami":{"get":{"operationId":"get_api_whoami","summary":"Who am I","description":"Returns the identity resolved from the presented credential, plus which auth scheme resolved it and the scope granted to the token.","tags":["Account"],"security":[{"schemavaults-access-token":[]},{"schemavaults-access-token-cookie":[]}],"x-schemavaults-auth":{"public":false,"schemes":["schemavaults-access-token","schemavaults-access-token-cookie"],"routeGuard":"authenticated","requiredScopes":[],"organization":null},"responses":{"200":{"description":"The caller's identity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Whoami"}}}},"401":{"description":"No valid SchemaVaults credential was presented","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential is valid but not allowed to perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/me/email":{"get":{"operationId":"get_api_me_email","summary":"My email address","description":"Only tokens whose `scope` claim includes `email` may read the address; tokens without a scope claim are refused with 403 insufficient_scope.","tags":["Account"],"security":[{"schemavaults-access-token":["email"]},{"schemavaults-access-token-cookie":["email"]}],"x-schemavaults-auth":{"public":false,"schemes":["schemavaults-access-token","schemavaults-access-token-cookie"],"routeGuard":"authenticated","requiredScopes":["email"],"organization":null},"responses":{"200":{"description":"The caller's email","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":["string","null"]}},"required":["email"]}}}},"401":{"description":"No valid SchemaVaults credential was presented","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential is valid but not allowed to perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/admin/ping":{"get":{"operationId":"get_api_admin_ping","summary":"Administrator ping","description":"Only platform administrators (users with the `admin` flag) may call this.","tags":["Admin"],"security":[{"schemavaults-access-token":[]},{"schemavaults-access-token-cookie":[]}],"x-schemavaults-auth":{"public":false,"schemes":["schemavaults-access-token","schemavaults-access-token-cookie"],"routeGuard":"admin","requiredScopes":[],"organization":null},"responses":{"200":{"description":"Admin pong","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","enum":["Admin pong!"]},"timestamp":{"type":"integer","description":"Unix epoch milliseconds when the response was produced","example":1757000000000}},"required":["message","timestamp"]}}}},"401":{"description":"No valid SchemaVaults credential was presented","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential is valid but not allowed to perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/organizations/{organization_id}/greeting":{"get":{"operationId":"get_api_organizations_organization_id_greeting","summary":"Organization greeting","description":"Demonstrates an organization membership requirement: the caller must be a member of the organization named in the path (platform administrators bypass the check). Membership is looked up on the auth server with this API server's JWKS access key.","tags":["Organizations"],"security":[{"schemavaults-access-token":[]},{"schemavaults-access-token-cookie":[]}],"x-schemavaults-auth":{"public":false,"schemes":["schemavaults-access-token","schemavaults-access-token-cookie"],"routeGuard":"authenticated","requiredScopes":[],"organization":{"parameter":"organization_id","roles":[],"adminBypass":true},"notes":"Any membership role is accepted."},"parameters":[{"schema":{"type":"string","minLength":1,"description":"Organization id"},"required":true,"description":"Organization id","name":"organization_id","in":"path"}],"responses":{"200":{"description":"A greeting for the organization member","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"400":{"description":"The organization id is missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"No valid SchemaVaults credential was presented","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential is valid but not allowed to perform this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{}}