Skip to navigation
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.

Concurrent creation can return 409 Conflict, leaving the stored configuration and tenant version unchanged. Read it before retrying, since a retry can update it. An explicit rotateKey: true request can instead rotate a concurrently created configuration found during the write.

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

orgstringOptional
Organization that owns the Tenant identity configuration
enabledbooleanOptional
Whether Tenant identity token delegation is enabled
issuerstringOptional
Issuer URL for Tenant identity tokens
defaultAudiencestringOptional
Default audience used for Tenant identity tokens
allowedAudienceslist of stringsOptional

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.

tokenTtlSecondsuintOptional>=0
Lifetime of issued Tenant identity tokens, in seconds
subjectPrefixstringOptional

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 objectsOptional

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.

createddatetimeOptional

Date/time when the Tenant identity configuration was created

updateddatetimeOptional

Date/time when the Tenant identity configuration was last updated

Errors

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