Onboarding Walkthrough

This is the ordered customer runbook for bringing up an EDK deployment and onboarding the first tenant. All calls go through the gateway:

• https://platform.<base-domain> for setup, operator sign-in, platform administration, and the admin console.
• https://<tenant>.<base-domain> for tenant protocol routes and protected tenant administration APIs.

Do not call workload container hostnames, container ports, health routes, or gRPC receivers directly. TLS terminates at the customer gateway with a certificate valid for platform.<base-domain> and *.<base-domain>.

Prerequisites

The enterprise stack is running from the published Nexus artifacts:

• Docker images from nexus.sphereon.com/edk-docker.
• Helm chart from https://nexus.sphereon.com/repository/edk-helm when deploying on Kubernetes.
• A platform database owned by the platform service.
• A separate tenant workload database used by tenant-KMS, DID, tenant-AS, issuer, and verifier, with schema-per-tenant isolation by default.

Step 1: Complete Platform Setup

Open the platform host:

https://platform.<base-domain>

Complete first-run setup there. Setup installs or imports the protected license bundle and creates the first platform operator account. The setup API exists at /api/platform/setup/v1 only while the setup gate is open; after setup it returns 404.

Reference: Platform onboarding.

Step 2: Sign In as Platform Operator

After setup, open:

https://platform.<base-domain>/admin-console

The operator signs in through the platform authorization server using the authorization-code flow with PKCE. Platform-admin calls carry the resulting operator bearer token.

Reference: Operator sign-in.

Step 3: Create the Tenant

Create the tenant from the admin console or through:

POST /api/platform/admin/v1/tenants

Tenant setup provisions the default tenant authorization server, the tenant-named KMS provider and default key aliases, the tenant did:web identifier, and the tenant gateway endpoint bindings. If issuer and verifier are selected, setup also creates and binds those instances.

Poll the onboarding correlation id until the workflow reports COMPLETED, then verify the tenant and gateway endpoint bindings through the Platform Admin API.

Reference: First tenant.

Step 4: Review the tenant authorization server

Postman OAuth and the first tenant client

Import the customer collection and environment. Set baseDomain, tenantSlug, and tenantName. Each top-level folder has its own OAuth2 configuration: open the folder, go to Authorization, choose Get New Access Token, then Use Token.

On 1. Platform operator, sign in with the platform operator account. In Tenants, List tenants remembers the tenant whose slug is tenantSlug, and Register tenant creates it when it does not exist yet. When no email transport is configured, the response and the Postman console show delivery.manualActivationLink: open it in a browser to set the tenant owner's password.

Your application calls the tenant APIs as a service client: an OAuth2 client of the tenant's own authorization server that uses the client credentials grant. On 2. Tenant owner: create a service client, sign in as the activated tenant owner. This folder uses the registered developer-postman client, PKCE S256, and the exact callback https://oauth.pstmn.io/v1/browser-callback. Choose serviceClientId, and set serviceClientSecret or leave it empty to let the collection generate one. Create the service client registers the client on the tenant's default hosted authorization server:

POST https://acme.example.com/api/platform/config/v1/tenants/{tenantId}/authorization-servers/{authorizationServerId}/clients
Content-Type: application/json

{
  "clientId": "tenant-api",
  "clientType": "confidential",
  "enabled": true,
  "grantTypes": ["client_credentials"],
  "tokenEndpointAuthMethod": "client_secret_post",
  "defaultAccessTokenAudience": "enterprise-platform",
  "allowedAccessTokenAudiences": ["enterprise-platform", "enterprise-tenant-as", "enterprise-tenant-kms", "enterprise-tenant-did", "enterprise-issuer", "enterprise-verifier", "enterprise-blob"],
  "principalRoles": ["tenant-admin"],
  "clientCredential": {
    "method": "client_secret_post",
    "clientId": "tenant-api",
    "secretValue": "<your private client secret>"
  }
}

A successful 201 response returns the client registration and an opaque clientCredential.secretReference; it does not return the secret value. If you no longer have the secret of an existing client, Replace the service client secret stores serviceClientSecret as the new one. You can also create the service client in the admin console under Authorization server > Clients and put its id and secret in the environment.

Select 3. Tenant APIs, then Get New Access Token and Use Token. The folder requests one client credentials token with an audience parameter for every tenant service, and all its requests inherit it. Platform operator tokens remain confined to platform administration and platform-owned shared resources. Use separate environments for separate tenants.

Postman manages the access tokens. Do not add a manual Authorization header or copy a token into a variable. The browser sign-ins do not run inside Newman; these are interactive customer examples.

Open the tenant Admin Console and choose Protocols, then Authorization Servers. Tenant setup creates the regular hosted resource and assigns it a stable UUID. Confirm its issuer, lifecycle, purposes, grants, hosted configuration, and signing-key binding before activating dependent issuer flows.

Create additional hosted resources only when the deployment needs an independent issuer or policy boundary. Add an external resource for an upstream OAuth or OpenID Connect provider. An external resource starts suspended. Validate its metadata, review the discovery snapshot and supported grants, then activate it explicitly.

For federated sign-in, create the external resource from its issuer, validate and activate it, then open the hosted resource's Federation tab. Create the binding disabled, choose the upstream client authentication method, write or select the typed credential reference, configure scopes and claims mapping, and validate the binding. Enable it only after validation succeeds. LOCAL_ONLY, FEDERATED_ONLY, and HYBRID are distinct hosted authentication modes. One eligible federated binding redirects automatically, several bindings produce an ordered chooser, and hybrid mode shows local sign-in with the eligible upstream choices.

Run a real authorization request after each routing change. Verify that prompt=none never renders a login form or chooser and that an upstream callback resumes only its original downstream transaction. The browser capture and sanitized API examples are evidence only when they come from the current live gateway flow.

If an upgrade converted earlier hosted configuration or tenant identity-provider records, open Migration remediation. Resume an unchanged failed source only when its recorded digest still matches. Use the separate audited Accept source change operation when an administrator has reviewed a changed source. Never create a replacement resource to bypass a failed coded migration.

The platform records migration completion only after every source is applied and the retired authority rows are removed. Once complete, later edits through the authorization-server administration surface are normal revision-guarded resource changes and are not treated as migration input on the next startup.

Reference: Tenant federation and authorization servers and Migration remediation.

Step 5: Bind authorization servers to the credential issuer

Open the credential issuer and review its authorization-server bindings. Enable every resource that the issuer may advertise and select exactly one default. Credential configuration and issuance template overrides store authorization-server UUIDs. The effective selection order is template override, credential-configuration override, then issuer default.

Run the protocol-profile dry run before applying a profile change. Resolve every reported credential, metadata, grant, binding, or template incompatibility before applying the new revision. Record the operator reason in the apply dialog. A repeated submission uses the same idempotency key and cannot create a duplicate transition. Existing offers keep their starting protocol profile; offers created after the successful apply use the new profile.

Reference: OID4VCI authorization-server selection and Issuance defaults.

Step 6: Use the Tenant Gateway

After onboarding, tenant calls use:

https://<tenant>.<base-domain>

Wallet-facing protocol paths and well-known documents are unauthenticated where the protocol requires it. Tenant administration paths, including KMS, DID, issuer, verifier, and DCQL administration APIs, require a tenant-scoped bearer token and are still reached through the tenant gateway host.

Reference: Tenant keys and did:web and Enterprise deployment walkthrough.

Step 7: Verify the customer API collection

Run the downloadable Postman collection through the gateway. 1. Platform operator lists or registers the tenant, 2. Tenant owner: create a service client creates the service client, and 3. Tenant APIs uses that service client for the developer journey: keys and DIDs, the credential issuer, credential designs, status lists, defining your own credential, issuing and receiving a credential in a test wallet, DCQL and verification, and trust domains. The Azure Key Vault and Keycloak wallet login folders are optional and skip themselves until you set their inputs.

The customer environment uses baseDomain, tenantSlug, tenantName, serviceClientId, and serviceClientSecret, plus the optional Azure Key Vault and Keycloak inputs. Platform and tenant URLs are derived from baseDomain and tenantSlug; the environment does not contain per-container service URLs or tokens.

The walkthrough publishes sanitized request and response panels only after the live gateway run has produced them. Admin Console screenshots likewise come from the real browser flow and the maintained frontend-to-docs copy pipeline. A placeholder panel or a screen-catalog entry marked wip is outstanding evidence; it is not replaced with a hand-authored response or mocked screenshot.

Reference: Downloads and Provisioning and onboarding.