Configuring authorization servers, issuers, and verifiers

Tenant-owned protocol services are administered through the Platform Config API at https://platform.<base-domain>/api/platform/config/v1. Platform Admin remains responsible for tenant lifecycle, domains, signup, and operator onboarding. Protocol configuration is tenant data and is therefore never written through platform-wide bootstrap or deployment settings.

See the Platform Config API reference for the complete request and response schemas.

Authorization server resources

A tenant can own multiple authorization-server resources. Every resource has a stable UUID and is addressed through:

/api/platform/config/v1/tenants/{tenantId}/authorization-servers/{authorizationServerId}

The tenant id is an operator-chosen nonblank identifier. The authorization-server id is a UUID. Slugs are display and lookup data only and must not be used as durable references. The retired /oauth2/as singleton and instance routes have no aliases.

Create either a hosted or external resource:

• A hosted resource runs inside VDX. Its configuration, signing reference, clients, identities, and federation bindings are managed below its UUID.
• An external resource represents an independently operated authorization server discovered over HTTPS. Creation accepts only its issuer as a discovery input and records the expected protocol capabilities. Validation and refresh use the hardened discovery transport and persist the validated snapshot and digest.

Resources follow the DRAFT, ACTIVE, SUSPENDED, and DECOMMISSIONED lifecycle. An external resource cannot become active until it has a current validated discovery snapshot satisfying its expected capabilities. Decommissioning is terminal.

Hosted configuration and signing

Hosted configuration is replaced atomically with the resource revision as the compare-and-set guard:

PUT /api/platform/config/v1/tenants/{tenantId}/authorization-servers/{authorizationServerId}/configuration

The request contains expectedRevision and the complete hosted configuration. A stale revision fails rather than partially applying settings. Signing configuration selects the tenant KMS provider and key alias for runtime use. Some Platform Config request versions also persist a kmsResourceHandle beside the alias as an internal management-resource binding; that opaque handle is not the selector for tenant KMS REST operations, which use providerId plus the key alias. Private key material is never accepted or returned by the Platform Config API.

The hosted settings cover token and code lifetimes, grants, features, device flow, token exchange, interactive authorization, and signed metadata. The durable authorization-server catalog is authoritative. Deployment configuration may seed or project defaults, but it is not a second administration store.

OAuth clients

Clients are first-class resources below the hosted authorization-server UUID. Public clients use none or a supported attestation method. Confidential clients use client-secret or private-key authentication.

For a client secret, choose exactly one write mechanism:

• supply a write-once secretValue so the server stores it through the tenant secret service;
• supply a typed secret-resource reference; or
• use a typed KMS reference where the selected authentication method supports asymmetric keys.

Raw secrets are redacted from every response. Replacement and deletion retain the internal secret record version so the exact superseded value can be retired durably.

Identities

Hosted identities are addressed below the authorization-server UUID. Role and enabled-state updates use one revision-guarded mutation. Session revocation is recorded through the same durable transaction boundary and completed from its outbox. The API does not expose the former tenant-global authorization-server identity routes.

External authorization servers and federation

An upstream OpenID Provider is modeled in two explicit steps:

1. Create an external authorization-server resource with its issuer and expected capabilities. The API derives the OAuth and OpenID discovery URLs and accepts no manual endpoint override. Validate it before activation and refresh it when its discovery document changes.
2. Create a federation binding below the hosted authorization-server resource that will use it.

Bindings have an explicit order and lifecycle. Create and update them disabled, validate the current upstream configuration, then enable them. Enabling requires the latest validation result to be VALID; disabling records DISABLED, so re-enabling requires a fresh validation. Credentials use write-once values or typed secret/KMS references and are never read back.

The sign-in runtime selects the binding from server-owned transaction state. It does not accept an arbitrary provider URL or slug from the browser. State, nonce, PKCE, issuer, audience, authorized-party, timestamp, replay, mix-up, and substitution checks are enforced before normalized upstream evidence may enter the local authorization transaction.

OID4VCI issuer bindings and profiles

An OID4VCI issuer can bind to multiple authorization-server UUIDs and must have exactly one enabled default. Credential-configuration and issuance-template overrides may select a different bound resource. Selection precedence is template override, credential-configuration override, then issuer default. Mixed authorization-server selection within one issuance transaction fails closed.

The issuer stores a governed protocol profile. Use the compatibility dry run before applying a new profile. Apply requires the expected revision, an operator reason, and a stable idempotency key. The profile change and immutable audit outbox record are one database transaction; cache invalidation occurs only after commit.

Authorization-server selection is frozen into the offer and issuance session. Standard grant-specific authorization_server metadata is emitted from that snapshot rather than recalculated later.

Migration remediation

Earlier hosted configuration and retired tenant-IdP records are migrated once into UUID resources by coded authorization-server authority migration version 1. PostgreSQL and MySQL use their own schema migrations and maintain equivalent authority ledgers and completion state.

Remediation operations are deliberately distinct:

• Resume retries a failed row only when its recorded source digest is unchanged.
• Accept source change is a separate audited command requiring the recorded digest, observed current digest, expected revision, authenticated actor, and nonblank reason.

Neither operation infers missing source data or silently accepts a changed configuration.

Issuer and verifier settings

OID4VCI issuer and OID4VP verifier settings remain tenant-scoped Platform Config resources. Credential designs, status lists, issuance templates, and DCQL queries stay in their dedicated authoring APIs and are referenced by stable identifiers instead of copied into protocol configuration.

Next, create signing keys and the tenant's did:web identifier.