Skip to main content
Version: v0.25.0 (Latest)

Onboarding Walkthrough

This is the ordered runbook for standing up an EDK deployment and onboarding a tenant. Each step states the concrete endpoint or config, a way to confirm it worked, and a link to the page that covers it in depth. Where it helps, the endpoint is shown inline below the step.

The Platform Admin API is mounted at /api/platform-admin/v1 on the AS image. The acting tenant always comes from the JWT; path-encoded {tenantId} segments name the operation target.

Prerequisites

The EDK containers (AS, KMS, DID, Issuer, Verifier) are running and connected to Postgres, and you can authenticate into the platform-admin REST with the deployment's initial operator credential. PostgreSQL holds the tenant registry; the tenant_bootstrap gate row exists with completed_at = null on a fresh deployment.

Step 0: Bootstrap the application tenant, hosted AS, and operator​

The application tenant is the tenant that administers the deployment. It always has a hosted Authorisation Server and owns the operator access path. Bring it up either from deployment config or through the bootstrap endpoint.

From config:

application.tenant.id=platform
application.tenant.hosted-as.issuer=https://as.platform.example
application.tenant.owner.email=ops@platform.example
application.tenant.owner.display-name=Platform Operator

Or through the API: bootstrap the application tenant with POST /application/tenant/bootstrap (bootstrapApplicationTenant), supplying the tenant name, slug, and the local owner.

Verify: GET /application/tenant (getApplicationTenant) returns the application tenant id and a TenantBootstrapStatus.

Reference: Platform Admin API. Link: Application Tenant and Bootstrap.

Step 1: Activate the license​

Install the deployment license, then confirm its signature and validity window. The license snapshot gates root-tenant registration, self-signup, subtenants, custom domains, and federation. Submit the signed license token with PUT /application/license, then check it with POST /application/license/verify.

Submit the signed license token. The response is the license snapshot: status, the licensed features, and the limits that gate registration.

PUT /api/platform-admin/v1/application/license

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Verify: GET /application/license (getApplicationLicense) reports status: ACTIVE with the licensed features and limits.

Reference: Platform Admin API. Link: License, Quota, and Policy.

Step 2: Select the secret backend​

Choose the backend that stores tenant and federation secrets as references. A non-dev backend is required before invite or self-service signup journeys are enabled. The backend enum is azure-key-vault, hashicorp-vault, kubernetes-secret-mount, or config-system-dev-only (local and development only). Set it with PUT /application/secrets/backend (putSecretBackend).

Set backend to one of the four values above; configRef points at the backend's connection settings stored in the deployment config. This selection governs where every per-tenant secret (federation client secrets, SMTP passwords) is written from then on.

PUT /api/platform-admin/v1/application/secrets/backend

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Verify: GET /application/secrets/backend (getSecretBackend) returns the selected backend.

Reference: Platform Admin API. Link: Per-Tenant Configuration.

Step 3: (Optional) Deploy the Email Service and set onboarding policy​

Email delivery is optional. When the deployment runs the enterprise-email-service container, point onboarding policy at it and set the signup toggles (root signup enabled, approval required, and so on) with PUT /application/onboarding (putApplicationOnboarding). Without an email service, admin direct creation and bootstrap still work, but admin invite and self-service signup do not.

Set the signup toggles (root signup, approval-required) and the email-service reference. The evaluated result is read back from onboarding/availability, where the license has the final say over config.

PUT /api/platform-admin/v1/application/onboarding

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Verify: GET /application/onboarding/availability (getApplicationOnboardingAvailability) reports which journeys are enabled and the reason for any that are not.

Reference: Platform Admin API. Link: Registration Journeys.

Step 4: Create the first real tenant​

Register a tenant with POST /tenants (registerTenant). The ownerDelivery.mode field decides owner activation: none completes activation out of band and works without email, email has the platform email the owner an invitation (and needs the email service). For the public path, use POST /tenants/signup/request (requestTenantSignup), gated by the selfSignup feature.

Supply the tenant name, slug, and tenantType, an owner, and the ownerDelivery.mode. Set hostedAs true to provision the tenant's platform-hosted AS during registration. The result carries the new tenant id and a correlationId for the onboarding timeline.

POST /api/platform-admin/v1/tenants

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Verify: the 201 response carries a correlationId. Poll GET /tenants/onboarding/{correlationId} for the per-step timeline.

Reference: Platform Admin API. Link: Registration Journeys.

Step 5: Owner completes activation​

The new tenant's owner activates the account by redeeming the one-time invitation token delivered out of band, plus the new credential they set. This is a public, unauthenticated endpoint: POST /owner/redeem (redeemOwnerInvitation).

The body is the one-time token and the credential the owner sets. The tenant is derived from the token, not from a session, so no authentication is required. The result identifies the activated owner and tenant.

POST /api/platform-admin/v1/owner/redeem

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Verify: the response identifies the activated owner and the tenant. The owner can now sign in.

Reference: Platform Admin API. Link: Owner Activation.

Step 6: Tenant configures its identity provider​

The tenant signs in with its own IdP. The default is platform-hosted (the platform's hosted AS acts as the tenant's IdP). To federate to the tenant's own OIDC IdP, register an external IdP with POST /federation/idps (createTenantIdp), supplying the issuer, clientId, claimsMapping, and the clientSecret (write-only in, returned only as clientSecretRef). Federation is gated by the federation license feature.

Supply the non-secret IdP metadata (issuer, clientId, scopes, claimsMapping) plus the write-only clientSecret. The response returns only clientSecretRef. Leave enabled false so the IdP is probed before it goes live.

POST /api/platform-admin/v1/federation/idps

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Verify: POST /federation/idps/{idpId}/test reports issuer reachability and metadata validity; then enable it with POST /federation/idps/{idpId}/enable.

Reference: Platform Admin API. Link: Tenant Federation.

Step 7: Make the tenant's issuer, verifier, and AS reachable​

Bind a public endpoint for each service so the tenant advertises and serves its OID4VCI issuer, OID4VP verifier, and OAuth2 AS at the right URLs.

One issuer, verifier, and AS per tenant

The EDK runs at most one of each per tenant. Running many instances of a service per tenant is a VDX capability and is not covered here.

Bind the issuer with PUT /tenants/{tenantId}/public-endpoints/{serviceType} (upsertTenantPublicEndpoint), using OID4VCI_ISSUER as the service type. The body sets where the service is advertised: a verified custom host, or a pathPrefix under the platform subdomain, plus the wellKnownPath. Repeat for the verifier (OID4VP_VERIFIER) and authorization server (OAUTH2_AUTHORIZATION_SERVER).

The tenantId and serviceType come from the path. The body advertises the service: either a verified custom host or a pathPrefix under the platform subdomain, plus the wellKnownPath. Set enabled true to serve it and primaryEndpoint true for the advertised default.

PUT /api/platform-admin/v1/tenants/{tenantId}/public-endpoints/{serviceType}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Verify: GET /tenants/{tenantId}/public-endpoints lists the binding; the issuer well-known document resolves at the advertised host.

Reference: Platform Admin API. Link: Instance Deployment.