Skip to content

Create a workload and its first credential

Register an administrative workload, such as a provisioning job or a key-rotation pipeline, give it a public key to sign in with, and assign the scopes it may use. A workload administers the tenant without a person; it never uses keys for cryptographic operations.

Who can do it

A tenant administrator, or a platform super admin working inside the tenant on a private-cloud or on-premise deployment. On a SaaS deployment the platform refuses a platform administrator's changes to a tenant's workloads.

The console shows each control only to a person who holds its permission: Create workload needs the permission to create workloads, Register public key the permission to manage workload credentials, and Assign scopes the permission to assign workload scopes.

Before you start

  • Whoever runs the workload generates its key pair and sends you only the public key, as a JWK: an EC key on P-256, P-384 or P-521, or an RSA key of 2048 to 4096 bits. You never receive or hold the private key.
  • Decide which scopes the workload needs. You can assign only scopes you hold yourself, and you must also hold every scope the workload already holds.
  • Registering a key and assigning scopes are refused during a support-access session.

Steps

  1. Open Administrative Workloads from the tenant sidebar.
  2. Select Create workload.
  3. Enter a Name and, optionally, a Description, then select Create. The name uses letters, digits, dots, hyphens and underscores, starts with a letter or a digit, and is unique among the tenant's workloads that are not revoked. The new workload's detail opens.
  4. On the Keys tab, select Register public key:
    1. Paste the public JWK into Public key (JWK).
    2. Optionally set Valid until. Left empty, the key is accepted for twelve months; no key is accepted for more than twenty-four.
    3. Select Register.
  5. On the Scopes tab, select Assign scopes, tick the scopes the workload needs, and select Save scopes. The list offers only the scopes the platform says you may assign; the set you save replaces the current one.
  6. Give the person who runs the workload its id, shown under its name in the detail.

What you see when it worked

The console confirms "{name} created.", then "Key {kid} registered." and "Scopes saved.". The workload is listed as Active, with one key in use and its scopes. The key appears on Keys as Active, identified by its thumbprint (Key ID). Each change is recorded in the audit trail.

The workload's next token carries the scopes you saved. Instead of a key, a workload can sign in with a cloud or CI identity; see Let workloads sign in with a cloud or CI identity.

If it fails

What you see Cause What to do
"A live administrative workload of this tenant already uses this name. Choose another name, or revoke the workload that holds it." A workload of the tenant that is not revoked already uses the name, compared without regard to case Choose another name
The name is rejected It has characters other than letters, digits, dots, hyphens and underscores, or does not start with a letter or digit Correct the name
"This key contains private key material, so it was cleared and not sent. Paste the public key only." The pasted JWK carries a private member Ask for the public key only
The key is refused An unadmitted key type, curve or RSA size, or a Valid until in the past or more than 24 months away Ask for an admitted key, or correct the date
"This public key is already registered. Generate a new key pair and register its public key." The key is already registered, on this or another workload Ask for a new key pair
"An administrative workload of this tenant cannot hold the following scope(s):", followed by the scopes A workload may not hold those scopes, such as a cryptographic data-plane scope other than the key and keystore imports, a platform scope or an audit scope Remove the listed scopes
"Refused by the subset rule:", followed by the scopes you do not hold You do not hold a scope you are assigning, or one the workload already holds Ask an administrator who holds them

Without the console

Surface How
API POST /api/v3/admin/tenants/{tenantId}/workloads (operation createTenantWorkload)
API POST /api/v3/admin/tenants/{tenantId}/workloads/{workloadId}/credentials (operation createTenantWorkloadCredential)
API PUT /api/v3/admin/tenants/{tenantId}/workloads/{workloadId}/scopes (operation replaceTenantWorkloadScopes)