Skip to content

Operations

An operation (operation ticket) is a time-limited ticket that authorizes use of one or more signing keys, each a limited number of times. Every sign order (POST /api/signorders) and certificate request (POST /api/certificates) names an operation. The Keyserver refuses the request unless that operation is approved, has not expired or been cancelled, and has uses left for the key. ROOT keys are not used under operations; see ROOT Keys.

Who may create, approve, and use an operation is set by roles. How approvals are collected is described in Approval Workflow.


Operation parameters

POST /api/operations takes these fields (full schema in the API Reference):

Field Type Required Meaning
new-keyusagerestrictions Array of {keyid, maxusagecount}, at least one entry Yes Which keys the operation may use, and how many times each (maxusagecount is at least 1). Each key may appear once
validms Integer, at least 1 Yes Validity window in milliseconds, counted from creation. See Validity window
description String, 16 to 4096 characters Yes Context shown to approvers
creatorowns Boolean, default true No Restricts the operation to the subject that created it. See Creator ownership
{
  "new-keyusagerestrictions": [
    { "keyid": "fw-prod", "maxusagecount": 1 }
  ],
  "validms": 600000,
  "description": "Controller firmware 2.4.0 release build",
  "creatorowns": true
}

The response (201) carries only the operation ID. Read the approval state and usage counts with GET /api/operations/{id}.

Creation is refused when:

  • a key does not exist or has been revoked (404)
  • a key is not yet INITIALIZED (409)
  • the subject lacks createoperation on one of the keys (403)
  • a key appears more than once (409)
  • description is outside 16 to 4096 characters (400)

See Creating an operation (POST /api/operations).


Operation lifecycle

stateDiagram-v2
    [*] --> Pending : POST /api/operations
    Pending --> Approved : required approvers met<br/>(immediate if 0 required)
    Pending --> Expired : validms elapsed
    Pending --> Cancelled : approver Revoke or<br/>DELETE /api/operations/{id}
    Approved --> Expired : validms elapsed
    Approved --> Cancelled : DELETE /api/operations/{id}
    Expired --> [*]
    Cancelled --> [*]

Diagram: POST /api/operations; required approvers met (immediate if 0 required); validms elapsed; approver Revoke or DELETE /api/operations/{id}; DELETE /api/operations/{id}

State Meaning
Pending Created, and at least one key still needs approvals. GET /api/operations/{id} reports approved: false. No key in the operation can be used
Approved Every key has its required approvals; approved: true. An operation whose keys all have Required Approvers 0 is approved when it is created, so the pipeline can sign immediately
Expired validms has elapsed since creation. Sign orders and certificate requests are refused with 410
Cancelled Cancelled with DELETE /api/operations/{id}, or by an approver's Revoke. Every request under it, including GET, is refused with 410 ("Operation is cancelled")

An approved operation stays usable until it expires or is cancelled. A sign order does not end it, and each key keeps its own remaining usage count.

A pipeline polls GET /api/operations/{id} until it reports approved: true, then submits its sign orders; the full sequence is in The approval workflow. GET still returns an expired operation and has no expiry field: the operation expires at createdms + validms.

Approval covers the whole operation

An operation is approved only when every key in it has its required approvals. Until then no key in it can be used, including keys that require none. See Approval applies to the whole operation.

Cancelling

A subject holding canceloperation on every key in the operation can cancel it at any time with DELETE /api/operations/{id}. When creatorowns is set, only the creator can; see Creator ownership. An approver's Revoke on the Approvals page, which needs revokeapproval on every key, also cancels the whole operation while it is pending; see Revocation. Cancelling stops further signing under the operation. Signatures and certificates already issued cannot be recalled.


Usage count

maxusagecount sets the maximum number of uses per key within a single operation. Set it to the number of signings the run needs, usually 1.

Each sign order, or each certificate issued with a CA key, increments that key's usagecount. When it reaches maxusagecount, further requests for that key are refused with 409. See Error Codes Reference.

Usage is tracked per key: one key can be used up while another still has uses left, and the operation is still reported as approved. The API has no operation-level exhausted or remaining-usage field. Read the per-key counts from GET /api/operations/{id} (keyusagerestrictions[].usagecount against maxusagecount).

A per-operation budget, not a rate limit

maxusagecount bounds one operation, not a subject's total signatures: a subject with createoperation can request another operation. Required approvers on the key, prompt role revocation, and identity-provider controls are what limit a compromised pipeline.


Validity window

validms sets how long the operation remains valid after creation. A short window limits how long a compromised pipeline could submit sign orders without anyone noticing, and stops an approval from being kept and spent later. After expiry, sign orders and certificate requests under it are refused, and the pipeline must create a new operation.

validms Window Fits
300000 5 minutes A tight window for automated pipelines
600000 10 minutes Allows for approval latency
3600000 1 hour Manual approval workflows

Creator ownership

creatorowns defaults to true. While it is set, only the subject that created the operation can:

  • read it with GET /api/operations/{id}
  • submit sign orders under it
  • submit certificate requests under it
  • cancel it with DELETE /api/operations/{id}

Any other subject gets 409 ("With creatorowns flag set in operation, only the operation creator can access the operation"), even when its roles allow the action. See Error Codes Reference. Approving and an approver's Revoke are not restricted by creatorowns.

Set creatorowns: false when one subject creates the operation and another uses it, for example a release job that creates the operation and separate build jobs that sign under it.


Using an operation

A sign order or certificate request under an operation is refused unless all of these hold:

Condition Otherwise
The operation exists 404
The operation is not cancelled or expired, and none of its keys has been revoked 410
creatorowns is not set, or the caller created the operation 409
The key has the right type: FW for sign orders, CA for certificate requests 409
The caller holds order (sign orders) or createcertificate (certificates) on every key in the operation 403
The operation is approved 409 ("Need more approvers")
The key is part of the operation 404
The key has uses left (usagecount below maxusagecount) 409

Response bodies and the other causes per request are in Error Codes.