API ReferenceTenant Identity

Create or Update Tenant Identity Configuration

View as Markdown
Create or update tenant identity (JWT-SVID) configuration for the org/site. User must have authorization role with `TENANT_ADMIN` suffix in the URL `{org}`. On first call the Core gRPC API generates a new ES256 signing keypair; on subsequent calls the existing keypair is reused unless `rotateKey: true` is supplied. Returns `201 Created` on first call, `200 OK` on subsequent updates. See the Tenant Identity tag description for upsert semantics and the `enabled` vs DELETE distinction.

Authentication

AuthorizationBearer
``` export JWT_BEARER_TOKEN="<jwt-bearer-token>" # Example org name: "acme-inc export ORG_NAME=<org-name> # Use the JWT bearer token in your API request auth header: curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://nico-rest-api.nico.svc.cluster.local/v2/org/$ORG_NAME/nico/user/current ```

Path parameters

orgstringRequired
Name of the Org
siteIDstringRequiredformat: "uuid"
ID of the Site

Request

This endpoint expects an object.
Without key rotationobjectRequired

Standard create-or-update of the tenant identity config. Use this shape when not rotating the signing key. signingKeyOverlapSeconds is not used here — it is only meaningful together with rotateKey: true and is rejected by the REST API in that combination. Switch to the “With key rotation” variant when you need to set it.

OR
With key rotationobjectRequired

Create-or-update of the tenant identity config that also forces a signing-key rotation. Both rotateKey: true and signingKeyOverlapSeconds are required.

Response

Tenant identity configuration replaced/updated

orgstring
Organization that owns the Tenant identity configuration
enabledboolean
Whether Tenant identity token delegation is enabled
issuerstring
Issuer URL for Tenant identity tokens
defaultAudiencestring
Default audience used for Tenant identity tokens
allowedAudienceslist of strings

Stored allowlist of audience strings. Always non-empty: when a PUT supplied an empty list, the Core gRPC API substituted [defaultAudience] before persisting. Issuance rejects audiences outside this list.

tokenTtlSecondsinteger
Lifetime of issued Tenant identity tokens, in seconds
subjectPrefixstring

SPIFFE ID prefix used in the JWT sub claim. When the PUT body omitted subjectPrefix, Core stored spiffe://<trust-domain-from-issuer> here, so the value returned by GET may differ from what was submitted.

signingKeyslist of objects

Per-org signing keys currently published in JWKS. Exactly one entry has currentSigner: true. During a rotation overlap window a second entry is present with currentSigner: false and a populated expireAt; once the overlap window elapses the Core gRPC API deletes the expired entry and only the current signer remains.

createddatetime

Date/time when the Tenant identity configuration was created

updateddatetime

Date/time when the Tenant identity configuration was last updated

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error
503
Service Unavailable Error