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

Tenant Keys and the did:web Identifier

Tenant setup creates the default tenant KMS provider, the signing keys used by AS, issuer, and verifier, and a did:web identifier anchored on the tenant gateway host. Customer calls go through https://<tenant>.<base-domain> with a tenant-scoped bearer token; they do not address workload containers or east-west gRPC ports directly.

Verify the tenant KMS resource​

List the KMS offerings made available to the tenant:

List KMS offerings

Endpoint: GET /api/platform/config/v1/tenants/00000000-0000-4000-8000-000000000000/kms/offerings

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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

The optional platform setup flow creates a typed KMS resource. Its response exposes an opaque management handle and read-safe state, never key or credential material. This handle is for platform configuration lifecycle operations; it is not the selector used by tenant cryptographic calls:

List KMS resources

Endpoint: GET /api/platform/config/v1/tenants/00000000-0000-4000-8000-000000000000/kms/resources

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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

Validate the resource before relying on it for runtime signing:

Validate tenant setup KMS resource

Endpoint: POST /api/platform/config/v1/tenants/00000000-0000-4000-8000-000000000000/kms/resources/krh_%3Copaque%3E/validate

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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

Tenant runtime KMS calls​

After a provider is active, tenant applications use the tenant KMS REST API for cryptographic operations. Select the provider with its stable providerId and select the key with its provider-native alias (keyAlias or the endpoint's alias path parameter). The same provider-and-alias convention applies to public-key and certificate reads. Do not replace these selectors with the platform management resource handle.

The resource lifecycle examples above are configuration/setup operations for platform administrators. They show how a managed or shared provider becomes available; they do not define the tenant runtime KMS contract. The KMS REST API reference is the source for the operation-specific providerId and alias fields.

Disposable software KMS lifecycle​

The collection exercises the full typed-resource credential lifecycle on a disposable software resource: create, read the write-only credential status, attach the keystore credential, validate, rotate the credential, detach, and retire. Detach and retirement remove only this disposable resource; activation-created keys and DIDs remain untouched.

Create disposable SOFTWARE KMS resource

Endpoint: POST /api/platform/config/v1/tenants/00000000-0000-4000-8000-000000000000/kms/resources

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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

Read SOFTWARE KMS credential status

Endpoint: GET /api/platform/config/v1/tenants/00000000-0000-4000-8000-000000000000/kms/resources/krh_%3Copaque%3E/credentials/software-keystore

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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

Attach SOFTWARE KMS credential

Endpoint: PUT /api/platform/config/v1/tenants/00000000-0000-4000-8000-000000000000/kms/resources/krh_%3Copaque%3E/credentials/software-keystore

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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

Validate disposable SOFTWARE KMS resource

Endpoint: POST /api/platform/config/v1/tenants/00000000-0000-4000-8000-000000000000/kms/resources/krh_%3Copaque%3E/validate

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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

Rotate SOFTWARE KMS credential

Endpoint: POST /api/platform/config/v1/tenants/00000000-0000-4000-8000-000000000000/kms/resources/krh_%3Copaque%3E/rotate

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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

Detach disposable SOFTWARE KMS resource

Endpoint: POST /api/platform/config/v1/tenants/00000000-0000-4000-8000-000000000000/kms/resources/krh_%3Copaque%3E/detach

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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

Retire disposable SOFTWARE KMS resource

Endpoint: POST /api/platform/config/v1/tenants/00000000-0000-4000-8000-000000000000/kms/resources/krh_%3Copaque%3E/retire

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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

Shared cloud KMS providers​

The platform can offer one platform-owned cloud KMS provider connection to multiple tenants using SHARED_INSTANCE fulfillment. The provider configuration, provider revision, credentials, and operation locator remain platform-owned. The tenant receives an entitlement to use that provider, not a copy of its configuration or credentials.

Each tenant still owns its key and certificate reference records, logical aliases, list results, workload identity, and audit trail. Key and certificate lists come from those tenant reference indexes. They are never constructed by enumerating every object in the shared cloud account. For keys that EDK generates or imports under platform lifecycle control, the provider adapter translates the logical alias into a tenant-specific backing alias. For an externally managed registration, the supplied AWS, Azure, or other provider alias and provider ID remain unchanged because they identify an object that already exists in its native cloud environment.

Reference sharding prevents one tenant from listing or resolving another tenant's registered references, but it does not prove ownership when a tenant first supplies an existing provider-native alias. An externally managed AWS KMS key or Azure Key Vault key or certificate reached through a shared provider must therefore have the native cloud tag sphereon-tenant-id set to the authenticated EDK tenant ID. EDK checks the assignment before registration and again before later use. Missing, mismatched, unreadable, or removed assignments fail closed. This tag is not required when the provider resource itself is owned by the tenant instead of shared by the platform.

The tenant must explicitly enable an offered shared provider before using it. Disabling or withdrawing the entitlement prevents new operations immediately, including operations against references that remain registered for that tenant. It does not delete the cloud keys, cloud certificates, provider connection, or another tenant's references. TEMPLATE remains available when each tenant should receive its own cloned typed KMS resource instead.

The Postman collection contains the shared-provider lifecycle as disabled-by-default setup material. It requires an explicitly authorised provider-backed environment; enable it only when the target tenant has an active provider and the required permissions, then verify the returned provider and resource state before using it for signing.

The shared-instance offer (PUT .../sharing with SHARED_INSTANCE) switches fulfillment on the same platform resource while keeping the platform-owned configuration hidden from the tenant. The tenant must explicitly enable the offered provider before using it, and disabling or withdrawing it prevents new operations without deleting cloud resources or another tenant's references.

The tenant enables the offered provider, may select it as default, and sees it in the runtime provider list:

Disabling, withdrawing, detaching, and retiring reverse the offer without deleting any tenant key or certificate reference:

Optional external KMS registration​

The Postman collection includes a disabled-by-default folder for references to existing external KMS resources. It requires an active, tenant-authorized provider and uses collection variables for the example values. It does not create or import private key material.

Register an existing external key with its exact provider alias and optional canonical kid, or use the alias-only form when the provider can resolve the alias without a caller-supplied kid. EDK does not add its generated-key tenant prefix to that native alias. When using a platform-shared AWS or Azure provider, first assign the cloud object to the tenant with sphereon-tenant-id=<tenantId>. Read the registered key through the tenant KMS API to confirm that provider-supplied public JWK metadata is preserved without exposing private JWK members or x5u.

For AWS KMS, register a public leaf-to-root DER chain as stored_public_material and link it to the external key reference. For Azure Key Vault, register a provider-native leaf as provider_native; the later read delegates to the provider and does not follow AIA URLs or export a secret or PFX.

Public JWK projections retain provider-supplied x5c, x5t, and x5t#S256 when available. x5c uses padded standard Base64 DER. Thumbprints use unpadded Base64url. x5u remains excluded because it is a remote locator.

DELETE is reference-only for externally managed registrations. The requests remove the local EDK references and leave the provider resources untouched. Repeating either DELETE after the local reference is removed is idempotent and returns HTTP 204.

The disabled Postman requests remain available for an authenticated QA run. This guide deliberately does not render response panels for those untested cloud-provider operations; the provider-scoped runtime calls are documented in the Admin Console Keys and DID guide.

Resolve the activation DID​

The default did:web identifier uses the tenant gateway host. Resolvers turn did:web:acme.example.com into https://acme.example.com/.well-known/did.json:

List activation-created DID identifiers

Endpoint: GET /api/did/v1/identifiers

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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

Resolve activation-created DID

Endpoint: GET /api/did/v1/identifiers/did%3Aweb%3Aacme.example.com

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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

The DID document references the setup-created authentication and assertion keys:

List activation-created DID verification methods

Endpoint: GET /api/did/v1/identifiers/did%3Aweb%3Aacme.example.com/verification-methods

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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

The public hosting surface serves the DID document at the standard well-known location, unauthenticated and cacheable. This is the URL external resolvers use:

Fetch hosted activation did.json

Endpoint: GET /.well-known/did.json

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.

Live against connected environment

Connect an environment to rewrite this call to real service bases and run it.

Next, bind the issuing identity to this DID.