Onboard a tenant
A tenant is an isolated organization on the platform: its own routing host, authorization server, key store, and (when you enable them) issuer and verifier. Onboarding creates that isolation and starts the default services your product needs before anyone configures keys, credential designs, or protocols for that organization.
What actually gets created depends on the capabilities you select and on how your product implements onboarding. This guide covers the Admin Console wizard and the matching Platform Admin REST calls. It is not a commercial packaging recipe.
Audience: platform operator.
Prerequisites: Platform setup finished (license active, setup gate closed). Operator access to the Admin Console and/or a platform operator bearer token. See Open the console and Operator sign-in.
Related: Tenants reference, deployment walkthrough First tenant.
Connect an environment (bottom-right) if you want to Run Platform Admin calls live or open the console against a connected host.
Before you start
Decide these before you open the wizard:
- Slug: short, stable host label (lowercase letters, digits, hyphens). Many deployments publish the tenant at
https://{slug}.{base-domain}. The slug is hard to change later; treat it as permanent. - Display name: human-readable organization name for operators and invitations.
- Technical contact: person who receives operational notices for this tenant.
- Owner/admin: the account that will sign in to administer the tenant (often the same person as the technical contact).
- Capabilities: whether this tenant needs a credential issuer, a presentation verifier, automatic keys/DIDs, and sample designs/data for lab or demos. Sample data also provisions the docs-playground OAuth client as a side effect when that feature is enabled on the platform.
List tenants
- Admin Console
- REST API
Navigation: Platform > Tenants (operator landing after sign-in).
Use the list to see which customer organizations already exist, their lifecycle status, and to start registration. An empty list only means no customer tenants yet; the platform management entry remains available.
Platform Admin on the platform origin (not a tenant host):
- Overview
- Request
- Response
List tenants
Endpoint: GET /api/platform/admin/v1/tenants
Captured response: 200 OK
This captured endpoint is shown from the E2E run; it is not mapped to one of the generated EDK REST API reference pages.
Connect an environment to rewrite this call to real service bases and run it.
Register a tenant
Register tenant opens a stepped wizard. Each step gathers a different decision; the platform does not create the tenant until you confirm on Review and choose Provision tenant. Registration then starts an asynchronous setup workflow. Keep the returned tenant id and correlation id (for live docs Run, store tenantId as a guide variable).
Tenant URL
The first step defines how the tenant is named and addressed.
- Name appears in the operator UI and in invitations.
- Slug is the durable URL segment. Subdomain products resolve the tenant from
{slug}.<platform-domain>. Reject UUID-shaped slugs; stick to lowercase labels. - Description is optional internal context for other operators.
Pick a slug that will still make sense months later. Renaming host labels after issuance and client configuration is painful.
- Admin Console
- REST API
The REST body carries the same decisions in one request (see full register call after the wizard steps).
People
This step records who is accountable for the tenant:
- Technical contact: operational and service notifications.
- Administrative contact: contractual or account matters. Small teams usually keep this the same person as technical.
- Owner/admin person: the natural person behind the first admin account. Reuse technical or administrative contact, or enter a different person.
Wrong contact data here means invitations and support routing go to the wrong people. Fix it before provision when you can.
- Admin Console
- REST API
Contacts and ownerAdmin.source appear on the register request body.
Login
Controls whether the owner gets a usable admin login after setup.
- When Owner/admin login is on and email is healthy, the platform sends an activation message after provisioning.
- When email is unavailable, provisioning can return a one-time manual activation link for explicit handoff (lab and break-glass cases).
- The default authorization server and key store are always required for a tenant that can sign in and use crypto; the product does not offer turning those off in this wizard.
Turn login off only when another process will create the first admin identity.
- Admin Console
- REST API
login.enabled and defaultAuthorizationServerRequired on the register body.
Capabilities
These flags choose which protocol and resource defaults the setup workflow creates:
| Flag | Meaning |
|---|---|
| Credential issuer | OID4VCI issuer instance and public endpoints for this tenant |
| Presentation verifier | OID4VP verifier instance and public endpoints |
| Keys and DIDs | Default key material and identifiers used by issuer/verifier/AS (only meaningful if a protocol is selected) |
| Sample data | Lab designs, status/testing seeds, and related demo fixtures. Not production content. Also seeds the docs-playground client when sample data is selected |
Disable issuer/verifier for pure relying-party or admin-only tenants. Leave sample data off for production onboarding.
- Admin Console
- REST API
provisioning.issuer, verifier, keysAndDids, sampleData.
Review and provision
Review is the last chance to correct name, slug, contacts, and capabilities before anything is written. Provision tenant posts the registration and moves into progress tracking on the same step.
If registration fails with east-west or service-identity errors (REMOTE_PLATFORM_CONFIG_UNAVAILABLE, missing internal client secret), fix deployment secrets first. See First tenant.
- Admin Console
- REST API
- Overview
- Request
- Response
Register tenant
Endpoint: POST /api/platform/admin/v1/tenants
Captured response: 201 Created
This captured endpoint is shown from the E2E run; it is not mapped to one of the generated EDK REST API reference pages.
Connect an environment to rewrite this call to real service bases and run it.
Wait for setup
Setup is asynchronous. Status COMPLETED means the defaults you requested (AS, contacts, owner account, optional issuer/verifier/keys/sample data) finished successfully. Until then, do not assume issuer metadata or public endpoints are ready.
In the console, the review step shows delivery outcome and a step timeline. Wait for the tenant list refresh note, then Done.
Over REST, poll onboarding status with the correlation id from registration.
- Admin Console
- REST API
- Overview
- Request
- Response
Get tenant onboarding status
Endpoint: GET /api/platform/admin/v1/tenant-onboarding/00000000-0000-4000-8000-000000000000
Captured response: 200 OK
This captured endpoint is shown from the E2E run; it is not mapped to one of the generated EDK REST API reference pages.
Connect an environment to rewrite this call to real service bases and run it.
Confirm the tenant
Confirm the tenant is visible and usable before you hand work to tenant admins or start KMS/DID work.
- Lifecycle should progress to ACTIVE (or your product's ready state) once onboarding completes.
- Open the tenant to enter tenant context. Resource and protocol screens are scoped to that selection.
- Admin Console
- REST API
Open the tenant from the list after Done. Check name, slug, and status, then select the tenant context for Resources and Protocols.
Get by id:
- Overview
- Request
- Response
Get tenant
Endpoint: GET /api/platform/admin/v1/tenants/00000000-0000-4000-8000-000000000000
Captured response: 200 OK
This captured endpoint is shown from the E2E run; it is not mapped to one of the generated EDK REST API reference pages.
Connect an environment to rewrite this call to real service bases and run it.
List again if you need the full roster:
- Overview
- Request
- Response
List tenants
Endpoint: GET /api/platform/admin/v1/tenants
Captured response: 200 OK
This captured endpoint is shown from the E2E run; it is not mapped to one of the generated EDK REST API reference pages.
Connect an environment to rewrite this call to real service bases and run it.
Public endpoints and runtime discovery
Products publish protocol surfaces (authorization server, issuer, verifier, DID resolution) on the tenant public host. Setup creates those bindings when you enabled the matching capabilities. Operators rarely edit them by hand.
REST can list public endpoint bindings and resolve browser-safe runtime-config (base URLs for later KMS, DID, and design calls).
- Admin Console
- REST API
After activation, open the tenant product overview. Protocol instances appear under Protocols when provisioned. Resource products appear under Resources.
- Overview
- Request
- Response
List tenant gateway endpoint bindings
Endpoint: GET /api/platform/admin/v1/tenants/00000000-0000-4000-8000-000000000000/public-endpoints
Captured response: 200 OK
This captured endpoint is shown from the E2E run; it is not mapped to one of the generated EDK REST API reference pages.
Connect an environment to rewrite this call to real service bases and run it.
- Overview
- Request
- Response
Resolve tenant runtime service discovery
Endpoint: GET /api/platform/bootstrap/v1/runtime-config/admin-console
Captured response: 200 OK
This captured endpoint is shown from the E2E run; it is not mapped to one of the generated EDK REST API reference pages.
Connect an environment to rewrite this call to real service bases and run it.
After onboarding
- Keys and DID: confirm or create cryptographic keys and identifiers
- Credential designs: define what you issue
- Status lists and revocation: if credentials are revocable
- Issue credentials / Verify credentials
If sample data was selected, designs and related seeds may already exist. Review them before production use.