Capability Grants
What this screen is for
A capability grant authorizes one cryptographic actor to perform named operations on named keys, inside one exchange context. It answers four questions in one record: who may act, what they may do, on which keys, and under which conditions. This screen lists the grants in your tenant and is where you create standalone grants and revoke them.
Calling the cryptographic API takes a credential, an operation permission carried in the actor's token, and a grant. An active grant supplies the permission as well: while it is active the actor's tokens carry the matching operation permission, and when the grant goes the permission goes with it. Every operation is still checked against the grants when it runs.
What must exist first
This screen is for tenants that compose authorization by hand. It is not offered to SIMPLE tenants: a SIMPLE tenant uses Internal Use Cases, which create the grants each use case needs.
Before you work here:
- A cryptographic actor to receive the grant, and the keys the grant will name.
- An active exchange context that no internal use case owns. Every grant belongs to one, and the wizard cannot finish without it.
- The permission to list capability grants, which shows this screen. Creating and revoking are further permissions. Creating also needs the permission to assign actor roles when the grant would give the actor an operation permission it does not already hold.
Decisions you make here
Creating a grant
With the permission to create capability grants, New Grant opens a six-step wizard: the actor, the capability, the keys, the exchange context, the constraint policy, and a review that shows the operation permission the grant will confer. Create Grant writes it, and it takes effect at once.
Creation is refused while an operator is acting as someone else, when the actor is not active, and when the actor belongs to an internal use case, which acts only for its use case.
Choosing the operations
The capability step offers ENCRYPT, DECRYPT, SIGN and VERIFY, which one grant may combine, and the transformations REENCRYPT and RESIGN. A transformation moves data from source keys to target keys, so a grant carries exactly one of them and no other capability: issue the others as their own grants.
A grant that carries several operations has one usage budget. Under a policy with a usage limit or single use, every admitted call counts against the same limit, whatever its operation.
Choosing the keys
For single-key operations you choose one Asset key. For REENCRYPT or RESIGN you choose one or more ordered pairs, each with a source key and a target key, and Add pair adds another. Data under each source key moves to its target key, in that direction only; a pair whose source and target are the same key is valid.
Pick keys whose purpose matches the operations: a capability the key does not admit is refused when you create the grant, naming the key. A grant that writes with its key (ENCRYPT or SIGN) needs an active key.
Instead of a key, you can tick the wildcard box for single-key operations. The grant then applies to every key in your tenant, including keys created later. Keep it for an actor that genuinely needs every key.
Choosing the exchange context
Every grant belongs to one exchange context: the business frame it authorizes in. The list offers active contexts that no internal use case owns; when there is none, the step says so and sends you to Exchange Contexts. Suspending or closing the context stops the grant with it.
Choosing a constraint policy
A grant may reference one constraint policy, or stay Unconstrained. The grant pins the policy's current version, and the review shows which. The constraint policies screen explains each limit and the schedule.
Grants never overlap
An actor's live grants never overlap. A grant whose operations and keys intersect a live grant of the same actor, in any exchange context, is refused: "This grant would overlap a live grant of the same actor. Nothing was written." The wizard lists each conflicting grant as a link to it. Revoke or narrow the one in the way, or narrow the new grant.
When a grant is used up
A grant whose policy allows a single use, or a maximum number of uses, is consumed by the use that exhausts it, whether or not that operation succeeded. The Consumption column says why, after how many uses and when; it shows a dash while the grant is in force. Consumed grants stay in the list, dimmed and without Revoke. Revoked grants leave it.
Revoking a grant
With the permission to revoke capability grants, Revoke opens a confirmation. Type the actor's name back, or the grant's identifier when the actor has none, and fill in Why is this grant being revoked?: the reason is required and is recorded in the audit trail. A revoked grant cannot be restored.
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. Other grants of the actor are unaffected.
A grant that an active exchange owns is not revoked here: revoke it on the exchange's grants step, or revoke the exchange. When an exchange ends, its grants are withdrawn with it.
Changing a grant's limits
A grant's actor, operations, keys and context never change. Its limits change through Change version, which pins it to another version of any constraint policy. It is offered on an exchange's grants step and in the exchange topology panel.
Opening a grant
Selecting a grant's row opens its detail beside the list, with an Info tab and an Activity tab. Info shows the grant's identifier, actor, capabilities and the operation permissions they confer, keys or Every key in this tenant (wildcard), exchange context, constraint policy with its pinned version, when it was created and updated, and its state: In force or consumed. A revoked grant is no longer served; its detail says so, and Activity still shows its history.
Activity shows the changes made to the grant and every cryptographic operation it authorized. All, Administration and Usage choose between both, the changes only, and the operations only. View in Audit Log opens the Audit Log narrowed to this grant.
How it relates to other screens
In the list, a grant's actor, exchange context and constraint policy are links to their own details. The Exchange column names the grant's exchange context. Every key a grant names opens its own read-only summary.