Versioning

Path versioning

The Atlas API is versioned in the path. Every endpoint lives under /v1/…:

https://api.atlas.dev/v1/users
https://<instance>.fapi.atlasauth.net/v1/client

Within a major version the contract only grows in backward-compatible ways:

• New endpoints, new optional request fields, and new response fields may be added at any time.

• Existing fields are not removed or repurposed, and error codes are never renamed silently.

Write your clients to ignore unknown fields so an additive change never breaks you.

Standards discovery

The OIDC/OAuth surface publishes its own capabilities so clients configure themselves rather than hard-coding:

• GET /.well-known/openid-configuration — the OpenID Provider metadata (host-based issuer, S256 PKCE, RS256 signing).

• GET /.well-known/jwks.json — the current public signing keys.

Signing keys rotate; always fetch JWKS (and cache with stale-if-error) rather than pinning a key.

SCIM & webhook contracts

• SCIM advertises its supported features and schemas at /scim/v2/ServiceProviderConfig, /scim/v2/ResourceTypes, and /scim/v2/Schemas.

• Webhooks carry a type per event and full resource objects (not diffs), so a consumer processing events out of order can still reconstruct state. The event catalog is published — see Webhook events.

Deprecations

When a field or behaviour is scheduled for removal in a future major version, it is documented here well ahead of time. Nothing in /v1 is removed without a new major path.