Skip to content

Issue, rotate or revoke an actor credential

Give a cryptographic actor a credential it can authenticate with, replace that credential on a schedule, or revoke one at once.

Who can do it

A tenant administrator or a tenant key manager, and a platform super admin working in a tenant on a private-cloud or on-premise deployment. Issuing, rotating and revoking are separate permissions: the console offers Issue Credential, the Rotate mode and the revoke control only to a person who holds the matching one.

Before you start

  • The actor is not disabled. A disabled actor can never authenticate again, so issuing or rotating a credential for it is refused; revoking its credentials stays available.
  • Decide the credential type:
    • a shared secret, which the platform generates, shows once and keeps only as a hash;
    • a registered key pair, where the workload keeps its private key and you paste only the public key as a JWK.
  • For a rotation, decide how long the current credentials keep working. By default they keep authenticating for 24 hours.

Steps

  1. Open Cryptographic Actors, select the actor and open Credentials.
  2. To issue or rotate, select Issue Credential, then choose the Mode:
    • Add issues a new credential beside the active ones, which keep working.
    • Rotate issues a new credential and moves the active ones to ROTATING_OUT. Set the Grace window (hours), from 0 to 720: they keep authenticating for that long and are then revoked. 0 revokes them at once.
  3. When adding, choose the Credential Type: Shared secret, or Registered key pair and paste the Public JWK. A rotation keeps the type it replaces.
  4. Optionally set Valid From and Valid Until. Left blank, the credential is valid from now with no expiry.
  5. Select Issue.
  6. For a shared secret, copy the Client ID and Client Secret, store them, confirm that you stored the secret, and select Dismiss. The secret is never shown again.

To revoke one credential:

  1. On Credentials, select the revoke control on the credential's row.
  2. Type the credential's version as shown, for example v2.
  3. Fill in Why is this credential being revoked?
  4. Select Revoke.

What you see when it worked

An issued credential appears in the list as active, with its version and validity. After a rotation the previous credentials read ROTATING_OUT with the time they are revoked. A revoked credential reads revoked, the console confirms "Credential v{version} revoked", and it is refused at the next token request. A token already issued with it stays valid until it expires, at most 15 minutes; to stop the actor at once, suspend it.

If it fails

What you see Cause What to do
"The credential was not issued" with "This actor is disabled, which is final, so it cannot be given a new credential." The actor is disabled Provision a new actor if the workload is still needed
"Grace window must be between 0 and 720 hours." The grace window is out of range Enter a whole number from 0 to 720
"Valid Until must be strictly after Valid From." The validity window ends before it starts Correct the dates
Rotate reads "(no active credentials to rotate)" The actor has no active credential Use Add
The public key is refused The JWK is malformed, of an unsupported key type or size, or does not fit the credential type Paste the public JWK of a supported key
The secret was lost It is shown only once Rotate to obtain a new one

Without the console

Surface How
API POST /api/v3/admin/tenants/{tenantId}/actors/{actorId}/credentials (operation createActorCredential)
API POST /api/v3/admin/tenants/{tenantId}/actors/{actorId}/credentials/rotate, with graceWindowHours (operation rotateActorCredential)
API POST /api/v3/admin/tenants/{tenantId}/actors/{actorId}/credentials/{credentialId}/revoke with a body carrying the reason (operation revokeActorCredential)