Capability Grants
What this screen is for
A capability grant authorizes one cryptographic actor to perform named operations on named keys. 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 active grants in your tenant and is where you create and revoke them.
Calling the cryptographic API takes three things: a credential, an operation permission carried in the actor's token, and a grant. An active grant supplies the second as well as the third — 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, and a refusal is recorded in the audit trail with its reason.
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. The wizard lists actors, exchange contexts and constraint policies with your permissions to list each of them; a list you cannot read is empty.
- The keys the grant will name. A grant can only name a key that exists in your tenant and has not been deleted.
- The permission to list capability grants, which is what shows this screen. Creating and revoking grants are further permissions, each held separately. Creating needs one more where the grant would give the actor an operation permission it does not already hold: the permission to assign actor roles. Without it creation is refused and says which permission is missing.
Decisions you make here
Creating a grant
With the permission to create capability grants, New Grant opens a wizard. You choose the actor, the operations, the keys, and optionally an exchange context and a constraint policy, then review everything before Create Grant. The grant takes effect as soon as it is created, and so does the operation permission it confers. Creation is refused while an operator is acting as someone else — that is checked before anything else — and refused when the actor is not active. It is also refused, as is its review, when the actor belongs to an internal use case: such an actor acts only for its use case, and the refusal names that use case so you can choose another actor.
Choosing the operations
Capability offers ENCRYPT, DECRYPT, SIGN, VERIFY, REENCRYPT and RESIGN. A grant authorizes exactly the operations you tick, so tick only what the actor needs.
REENCRYPT and RESIGN work from one key to another. They are operations in their own right: a REENCRYPT grant lets the actor move data from one key to another without letting it decrypt that data on its own. A single grant holds either these key-to-key operations or single-key operations, never both, and a mix is refused when you create it. To authorize both kinds, create two grants.
Choosing the keys
For single-key operations you choose one Asset key. For REENCRYPT or RESIGN you choose a Source key and a Target key. The grant then covers operations between those two keys in either direction, and within either key on its own, so name only a pair the actor may use both ways.
Pick keys whose purpose matches the operations: a key made to encrypt and decrypt cannot sign or verify, and a signing key cannot encrypt. The server checks this for you — a capability the key's stored operations do not admit is refused when you create the grant, naming the key — so a mismatch costs you a refusal here rather than a failure at the first request.
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 after it. That is the broadest authorization a grant can give: keep it for an actor that genuinely needs every key, and name keys everywhere else.
When you start a grant from a key in the Key Inventory, that key is already chosen and cannot be changed or replaced by the wildcard.
Narrowing to an exchange context
Exchange Context is optional. A grant with an exchange context authorizes its operations only inside that business relationship. A grant without one applies whatever context a request names, or none.
Whichever grant matches, an operation bound to a suspended or closed exchange context is refused. Suspending or closing a context therefore stops every grant that works inside it at once, without revoking any of them.
If an actor holds grants for the same operation and key in more than one exchange context, its requests must name the context they belong to, or they are refused.
Narrowing with a constraint policy
Constraint Policy is optional. A policy adds conditions that every use of the grant must meet: a validity window, a maximum number of uses, a rate per minute, and single use. A grant can reference one policy. Left Unconstrained, the grant is limited only by its actor, operations, keys and exchange context.
A grant enforces the version of the policy that was current when the grant was created, and keeps it. The Policy cell shows that version (version N) and a one-line summary of its limits: the maximum uses or unlimited, the rate per minute, blocked or none, single use, and the window as from … / until … (exclusive).
A later edit of the policy creates a new version that applies only to grants created afterwards. To give an active grant new limits, revoke it and create it again. The constraint policies screen explains how each condition behaves.
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. A consumed grant authorizes nothing more, no matter how long ago it was used. The Consumption column says Consumed, why (single use taken or usage limit reached), after how many uses and when, in your local time; it shows a dash while the grant is in force. Consumed grants stay in this list, dimmed and without Revoke, so their consumption remains visible; they authorize nothing. Revoked grants, and grants whose exchange expired or was revoked, leave the list.
Once the platform has recorded the consumption the grant is withdrawn: it authorizes nothing more, but unlike a revoked grant it stays in this list and readable by its identifier, with that consumption. An exchange that owned it shows Consumed.
Revoking a grant
With the permission to revoke capability grants, Revoke withdraws a grant. Its other grants, and other actors, are unaffected, and a revoked grant cannot be restored: create a new one if the authorization is needed again. Revoking does not take effect the instant you click it. A token the actor already holds stays valid for the rest of its life, up to 900 seconds by default, and the platform's grant cache can serve a withdrawn grant for up to 300 seconds more.
Revoking is refused while a cryptographic exchange still owns the grant's lifecycle — that is, while that exchange is in any state other than revoked, expired or consumed, including draft, ready, active and suspended. Act on the exchange instead, and there is nothing left for you to clean up here: when an exchange reaches a terminal state — because you revoke it, because it expires, because its grant is used up, or because the application it belongs to is deleted — the grant it composed is withdrawn at the same moment, with the same delay before it stops working, and leaves this list unless it was used up: a consumed grant stays visible with its consumption.
Suspending the exchange is the reversible form of the same thing. The grant stops working for as long as the suspension lasts and is not removed, and resuming the exchange restores it as the same grant.
Opening a grant
Selecting a grant's row opens its detail in a panel beside the list; a link, the key or Revoke inside the row does only its own job. The detail has two tabs, Info and Activity.
Info shows the grant's identifier; its actor; its capabilities and the operation permissions it confers; its keys, or Every key in this tenant (wildcard); its exchange context; its constraint policy with the version the grant keeps; when it was created (Created) and last changed (Updated, which reads "not provided by this server" when the server does not send it); and its state, In force or consumed with when, after how many uses and why.
The actor, the context and the policy open their own details. When a name could not be read, the identifier is shown instead, marked name not resolved. With the permission to revoke grants, Revoke is offered for a grant in force.
A revoked or expired grant is no longer served, but audit records still name it. Its detail still opens: Info says the grant is not in force or was not found in this tenant, and Activity still shows its history. A link that names no valid grant, a refused read and a failed one are each stated above the list, the last with Retry.
Reviewing a grant's activity
The Activity tab shows the changes made to the grant, such as its creation and revocation, and every cryptographic operation it authorized, whichever actor ran it. All, Administration and Usage choose between both, the changes only, and the operations only. Reading the grant's operations is its own audit permission, separate from reading changes: when one is refused or fails, the tab says which and still shows the other.
An audit service that cannot read a grant's operations is stated as a failure, never as an empty history.
Each kind states how many of its entries are loaded out of how many it holds, and Load more reads the next ones until the tab says that kind's history is complete. On All, the merged list goes back only as far as both kinds are loaded, and the tab states that date. View in Audit Log opens the Audit Log narrowed to this grant over the last 365 days.
How it relates to other screens
In the list, a grant's actor, exchange context and constraint policy are links: each opens that entity's detail on its own screen, the one detail the console keeps for it, with its activity. When a name cannot be resolved, the link shows the identifier marked name not resolved. Every key the grant names opens its own read-only summary in place: a REENCRYPT or RESIGN grant shows its source key and its target key, and each one opens. A wildcard grant names no key to open.
The actor a grant authorizes, and the roles assigned to it by hand, are managed on the actors screen. The permissions a grant confers are not listed there as roles — nothing is written when a grant is created. An actor cannot be deleted while grants still reference it:
The two optional narrowings are managed on their own screens:
Grants name keys held in the Key Inventory. Deleting an application revokes the grants of its actors.
A grant named in an audit record links back to its detail here: the grant of an operation in any entity's Activity, the grant field of an event's details, and the entity identifier of an administrative change to a grant in the Audit Log: