Discovery (.well-known)

Three unauthenticated, public endpoints let relying parties (any service that accepts IdentSphere-issued JWTs) verify tokens and discover the issuer without an auth hop. They're mounted outside the auth middleware by design.

::: tip Auth None. These are public by design — JWKS exposes only public keys, the revocation feed only opaque session-family UUIDs (no PII). :::

---

GET /.well-known/jwks.json

The RS256 public signing keys (JSON Web Key Set). A stateless verifier fetches these once (and on rotation) to validate access-token signatures locally.

Response

200 OK

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "2026-05-key-1",
      "alg": "RS256",
      "n": "0vx7agoebGcQ…",
      "e": "AQAB"
    }
  ]
}

In HS256-only mode (no RSA keypair configured) keys is an empty array — there is no public key to publish, and verifiers must share the symmetric secret out of band instead.

---

GET /.well-known/openid-configuration

A minimal OIDC-style discovery document so standard verifiers locate the issuer and JWKS automatically.

Response

200 OK

{
  "issuer": "https://auth.example.com",
  "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
  "token_endpoint": "https://auth.example.com/v1/login",
  "identsphere_revocation_list_uri": "https://auth.example.com/.well-known/identsphere-revocations.json",
  "id_token_signing_alg_values_supported": ["RS256"],
  "subject_types_supported": ["public"],
  "response_types_supported": ["token"],
  "grant_types_supported": ["password", "refresh_token"],
  "claims_supported": ["sub", "org", "email", "aal", "typ", "jti", "sid", "iss", "exp", "iat"]
}

identsphere_revocation_list_uri is a non-standard extension pointing at the revocation feed below. It is named distinctly so it is not mistaken for an RFC 7009 token-revocation POST endpoint.

---

GET /.well-known/identsphere-revocations.json

The session-revocation feed for stateless relying parties — the mechanism behind IdentSphere's ≤5s effective revocation without a per-request DB hop.

A stateless RP verifies an access token locally via JWKS, then rejects it if its sid (session-family) claim appears in this feed. The feed publishes the set of session-family IDs revoked within the last access-token lifetime, so it is self-pruning and small: once a full access lifetime has elapsed since a revocation, every token bearing that sid has already expired and the entry drops off.

Response

200 OK

• Cache-Control: public, max-age=5 — combined with the rolling window, an RP polling on this TTL achieves ≤5s revocation latency.

{
  "revoked_sids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
  "as_of": 1780000000,
  "window_secs": 900,
  "ttl": 5
}

Field	Type	Meaning
revoked_sids	string[]	Session-family UUIDs (the sid claim) revoked within the window. Reject any token whose sid is listed.
as_of	int	Unix timestamp the snapshot was taken.
window_secs	int	The lookback window = one access-token lifetime.
ttl	int	Suggested client poll/cache interval (seconds).

The feed never 500s — relying parties poll it constantly, so a query failure returns an empty list (tokens then simply expire normally) rather than an error. See Sessions for the end-to-end revocation model and the verifier contract.

---

Notes

• All three are safe to cache at the edge. JWKS and the discovery doc change only on key rotation; the revocation feed carries its own short Cache-Control.
• SCIM (/Users, /Groups, …) and SAML SSO (/:org/login, /:org/acs, …) endpoints exist but are not yet fully implemented (SCIM write paths return 501 Not Implemented). They are intentionally omitted from this reference until they ship; track the changelog for status.