Skip to content

Create a machine actor and give it roles

Create a cryptographic actor under an application, the identity a service, batch job or third party uses to call the platform, and give it the roles that decide which kinds of operation it may request.

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. The console offers New actor to a person who holds the permission to create actors. The first-credential and role steps of the wizard appear only to a person who also holds the permission to issue credentials or to assign roles.

Before you start

  • The tenant is not SIMPLE. A SIMPLE tenant does not use this screen: its internal use cases compose the actor, its credential and its grants.
  • The application the actor belongs to exists. Creating an application already creates its Default Cryptographic Actor, so create another actor only when you need a separate identity, for example one per external processor.

Steps

  1. Open Cryptographic Actors from the tenant's navigation.
  2. Select New actor.
  3. In Identity:
    1. Choose the Application.
    2. Enter a Display Name. The Actor Name is generated from it while Auto-generate from Display Name is on; turn it off to type the name yourself. Only lowercase letters, digits and hyphens are accepted, starting and ending with a letter or digit.
    3. Choose the Actor Type: Internal, Third-Party or Partner.
    4. Optionally enter a Description, a Purpose and a validity window, Valid From (UTC) and Valid Until (UTC).
  4. Select Next. The actor is created at this point.
  5. In First credential, choose the Credential Type and select Issue credential, or select Skip. Issuing a credential is described in Issue, rotate or revoke an actor credential.
  6. In Roles, tick the cryptographic operations the actor may request, then select Finish. Select Skip to leave the actor without roles for now.

To change the roles later, open the actor, go to Roles, select Manage, tick the roles the actor should hold and select Save.

What you see when it worked

The actor appears in Cryptographic Actors. Its detail shows it as active, with the roles you assigned on Roles. Until the actor has both a way to authenticate and at least one role, its Info tab shows "This actor cannot operate yet" and offers the missing steps.

A role says which kind of operation the actor may request. Which keys it may use is decided by capability grants.

If it fails

What you see Cause What to do
"Lowercase letters, digits and hyphens. Must start and end with alphanumeric." The actor name has other characters Correct the name
"Valid Until must be strictly after Valid From." The validity window ends before it starts Correct the dates
The name is refused as already taken A live actor of the same application has that name Choose another name
"No Applications in this tenant — create one first" The tenant has no application Register an application first
Saving the roles is refused naming a role That role is conferred by an active capability grant, and is withdrawn by acting on the grant Untick it and save again
Saving the roles is refused naming a use case An internal use case owns the actor, so it acts only for that use case Change the use case instead

Without the console

Surface How
API POST /api/v3/admin/tenants/{tenantId}/applications/{applicationId}/actors (operation createActor)
API POST /api/v3/admin/tenants/{tenantId}/actors/{actorId}/roles with the complete set of roles (operation assignActorRoles). The set replaces the roles assigned by hand: to add one, send the current set plus the new role