OpenAPI specifications — Versola Docs
VersolaVersola/docs
Pre-1.00.7.1versola.kzGitHub
RUEN

OpenAPI specifications

Where the machine-readable API contracts of Versola auth, central and edge live in the repository, and what each file covers.

Every Versola HTTP API is described by an OpenAPI 3.1 file that lives next to the code it describes, in the versola repository on the main branch. The files are the contract: open them in any OpenAPI viewer, or feed them to a client generator.

Auth: the OAuth 2.0 / OpenID Connect server

Public endpoints of the auth service. One file per endpoint group, in auth/open-api/.

SpecEndpointsBackground
authorize.yamlGET and POST /authorizeRFC 6749, PKCE, JAR, JARM
par.yamlPOST /parRFC 9126
token.yamlPOST /tokenRFC 6749, DPoP
introspect.yamlPOST /introspectRFC 7662
revoke.yamlPOST /revokeRFC 7009
userinfo.yamlGET and POST /userinfoOIDC Core
logout.yamlGET and POST /logoutFront-channel and back-channel logout
jwks.yamlGET /.well-known/jwks.jsonRFC 7517
metadata.yamlGET /.well-known/openid-configuration, GET /.well-known/oauth-authorization-serverRFC 8414

The endpoints behave differently per tenant security profile: the specs describe both, so read the profile notes in each file.

Central: the control plane

central/open-api/central.yaml describes the admin API the admin console is built on: tenants, clients, resources, scopes, permissions, roles, users, challenges, forms, locales, themes, JWKS, edges and system settings. The same file is rendered in the browser on the Central API page.

Edge: the traffic plane

edge/open-api/edge.yaml describes the browser login routes, the proxy route /resources/{resourceId}/{path}, /permissions/me and the /native/* endpoints used by mobile apps. See Edge overview for how they fit together.

Known gaps in the specs

The OpenAPI files lag the code in a few places. When a spec and observed behaviour disagree, the behaviour is the bug or the spec is: report it on GitHub.

  • authorize.yaml does not list response_mode or request.
  • token.yaml and introspect.yaml do not describe client_assertion or mutual-TLS client authentication.
  • introspect.yaml does not list cnf in the response.
  • central.yaml does not list POST /configuration/clients/edge-certificate/renew, POST /configuration/jwks/generate, GET /configuration/jwks/keys and POST /users/registrations.
  • The info.license fields in some specs name a licence other than the Versola Community License.