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, tenantSubdomain, and tenantName. Use 00 Start here to discover the platform endpoints, then Get New Access Token and Use Token on 01 Platform - create tenant. Sign in with the platform operator account.

After tenant creation completes, open the returned owner invitation in a browser. In 02 Tenant owner - register application, discover the tenant OAuth endpoints and obtain a token as the activated tenant owner. Both interactive contexts use the registered developer-postman client, PKCE S256, and the exact callback https://oauth.pstmn.io/v1/browser-callback.

Set a private local tenantServiceClientSecret and choose tenantServiceClientId. The client registration request uses the UUID of the tenant's default hosted AS:

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. Select 03 Tenant application, then Get New Access Token with Client Credentials and Use Token. Its requests inherit that tenant OAuth configuration. Platform operator tokens remain confined to platform administration and platform-owned shared resources. Use separate environments for separate tenants.

Postman manages administrative access tokens. Do not add a manual Authorization header or copy a token into a collection variable. The helper does not run the browser login 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. It starts with platform authentication and tenant provisioning, automates the one-time owner bootstrap, creates the tenant confidential client, and then uses the resulting tenant service token for the developer journey. The focused path creates designs, standalone status lists, issuer configurations, credentials, DCQL, trust domains, and verification. The advanced authorization-server, federation, migration, external-KMS, and profile-upgrade scenarios remain opt-in and disabled when their environment needs operator-only secret mutation, upgrade fixtures, or external provider resources.

The customer environment uses baseDomain, tenantSubdomain, tenant display/credential inputs, and operator/bootstrap secrets. platformUrl and tenantGatewayUrl are derived collection values; the environment does not contain per-container service URLs.

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.