Skip to content

Grant, re-version or revoke a capability

Authorize a cryptographic actor to perform named operations on named keys inside one exchange context, move a grant to another version of its constraint policy, or withdraw the grant.

Who can do it

A tenant administrator or a tenant key manager. The console offers New Grant only to a person who holds the permission to create capability grants, Revoke only with the permission to revoke them, and Change version only with the permission to re-pin them. A grant that would give the actor an operation permission it does not hold yet also needs the permission to assign actor roles.

This is for tenants that compose authorization by hand. A SIMPLE tenant uses Internal Use Cases instead, and the platform refuses these changes for it.

Before you start

  • The cryptographic actor exists and is active, and no internal use case owns it.
  • The keys exist, and their purpose admits the operations you will grant. A grant that writes with its key (ENCRYPT or SIGN) needs an active key.
  • An active exchange context that no internal use case owns.
  • Optionally, a constraint policy that limits how the grant may be used. See Define a constraint policy.

Steps

  1. Open Capability Grants from the tenant sidebar.
  2. To grant a capability, select New Grant and complete each step, selecting Next between them:
    1. The actor that receives the grant.
    2. The capabilities: ENCRYPT, DECRYPT, SIGN and VERIFY can be combined; REENCRYPT or RESIGN stands alone in its grant.
    3. The keys: one Asset key, or, for REENCRYPT and RESIGN, one or more pairs of a source key and a target key, adding each with Add pair. For single-key operations you can instead tick the wildcard box, so the grant applies to every key of the tenant, including keys created later.
    4. The exchange context.
    5. A constraint policy, or none to leave the grant unconstrained. The grant pins the policy's current version.
    6. The review, which shows the operation permission the grant will confer. Select Create Grant.
  3. To move a grant to another policy version, open Exchange Topology, select the grant's exchange (select its line, and when the line carries several exchanges, the exchange in the list), and select Change version on the grant. Only a grant in force offers it. Choose the Constraint Policy and the Version, then select Change version. The same control is on the grants step of the exchange editor. The Capability Grants screen itself does not offer it.
  4. To revoke a grant, select Revoke on its row. Type the actor's name back, or the grant's identifier when the actor has none, fill in Why is this grant being revoked?, and select Revoke.

What you see when it worked

  • Create: "Capability Grant created". The grant is listed and in force at once, and the actor's next token carries the operation permission it confers.
  • Change version: the grant is evaluated against the version you chose from its next request on. Uses made while it had no usage limit do not count toward a new limit; between limited versions the count continues.
  • Revoke: "Grant revoked". The grant leaves the list. Access does not stop instantly: a token the actor already holds keeps its permissions for up to 900 seconds, and a service may read a cached grant for up to 300 seconds more.

Every change is recorded in the audit trail; the grant's Activity tab shows its history.

If it fails

What you see Cause What to do
"This grant would overlap a live grant of the same actor. Nothing was written." A live grant of the actor already covers some of these operations and keys, in any context; the wizard links each one Revoke or narrow the grant in the way, or narrow the new one
"This actor belongs to an internal crypto use case and acts only for it, so it cannot receive authority here. Choose an actor that no use case owns." The actor belongs to an internal use case Choose another actor
"The exchange context is not active, so it accepts no new grant or activation." The context is suspended or closed Resume the context, or choose an active one
The key cannot carry a capability, naming the key Its state, purpose, algorithm or key operations refuse it Choose a key that admits the operation, or drop the capability
Creation is refused for conferring authority The grant adds an operation permission the actor lacks, and you cannot assign actor roles Ask an administrator who can assign actor roles
Creation is refused while acting as someone else You are in a support-access session Make the change as yourself
Revoking is refused because an exchange owns the grant An active exchange composes this grant Revoke it on the exchange's grants step, or revoke the exchange

Without the console

Surface How
Key management CLI ankasecure-km capability-grants create --actor-id <uuid> --context <uuid> --capability <capability> --asset-kid <kid> (--pair <sourceKid:targetKid> for a transformation, --constraint-policy-id <uuid>), or --body-file with the full request
Key management CLI ankasecure-km capability-grants re-pin --id <uuid> --constraint-policy-version-id <uuid>
Key management CLI ankasecure-km capability-grants revoke --id <uuid> --reason <text>
Admin SDK CapabilityGrantOperations.create(CreateCapabilityGrantRequest), replacePolicyVersion(UUID, ReplaceCapabilityGrantPolicyVersionRequest) and revoke(UUID, RevokeCapabilityGrantRequest)
API POST /api/v3/admin/tenants/{tenantId}/capability-grants (operation createCapabilityGrant)
API PUT /api/v3/admin/tenants/{tenantId}/capability-grants/{grantId}/policy-version (operation replaceCapabilityGrantPolicyVersion)
API POST /api/v3/admin/tenants/{tenantId}/capability-grants/{grantId}/revoke (operation revokeCapabilityGrant)