Versioning

Every documented operation is under /api/v1. The prefix is our contract: if your client pins it, it keeps the shapes on these pages.

Stable inside /api/v1

• No operation is removed; paths and methods stay.
• No response field is removed or renamed, and no field changes type.
• No optional request field becomes required.
• No status code or error code changes for an existing condition.
• No permission stops allowing what it allows today.

We ship any of those as a new prefix, /api/v2, running beside v1.

Changes without notice

We may make these at any time:

• New operations.
• New response fields.
• New optional request fields.
• New error codes for conditions that had none.
• Plan ceilings, latency and array order.

Read the fields you need and ignore the rest. Handle an unknown error code by status:

Current codes: error codes.

Discovery paths

https://penv.cloud/.well-known/openid-configuration
https://penv.cloud/.well-known/jwks

Unversioned, because the protocol fixes the paths: a relying party derives {iss}/.well-known/openid-configuration from the token's iss and follows its jwks_uri (OpenID Connect Discovery). Both are public and unauthenticated, and we cache them for 300 seconds. See discovery.

The SCIM endpoint, /api/scim/v2/{connectionId}, carries the SCIM protocol's own version, not ours. You configure it in the console, and it is outside this reference.

OpenAPI document

https://penv.cloud/openapi.json

Describes every operation on these pages. Point your client generator at it. The per-operation pages under Secrets, Dynamic, Auth and Discovery are generated from it; the four overview pages are hand-written.

Next: secrets.