Approval workflow
A four-eyes gate on top of RBAC: when the project's approval policy gates an operation for an operator, that operator doesn't execute the operation directly — they file a request that a project admin approves, and only then does it run. This page deepens the approval overview.
What can be gated
The gate covers two families of operator action: the certificate lifecycle and the distribution-side supply chain. Each project has its own approval policy under Settings → Approvals (with that project selected). It names, per operation, which operators must get approval:
| Mode | Who needs approval |
|---|---|
No approval (off) | Nobody. |
All operators (all) | Every operator of the project. |
Selected operators (selected) | Only the users listed, and the members of the groups listed. A user who is listed directly or belongs to any listed group is gated. |
A group linked to LDAP gates whoever LDAP puts into it: a user who leaves the LDAP group leaves the CertAutoPilot group at the next sign-in and is no longer gated by that rule. Where users can change their own directory groups (self-service groups), list the operators directly or use All operators. A Selected operators rule whose users and groups were all removed (deleted, or no longer members) gates nobody; an admin's action under it is then not recorded as auto-executed.
Admins and owners are never gated — they act directly and approve the requests. An operator who holds an admin grant on a resource acts as an admin there (see resource grants), so it is not gated on that resource either.
Only an organization owner can change a project's policy, so a project admin cannot lift the approval its own operators are under. Every project member can read it, and the page shows each user whether they need approval; who is on a Selected operators list is shown to project admins and owners only. A project that never saved a policy uses the defaults below.
The approval switches used to be organization-wide, under Settings → General → Approval Requirements. They are now per project. Values saved under General before the upgrade are not carried over: every project starts from the defaults.
Certificate-lifecycle operations
All off by default:
| Operation | Gates |
|---|---|
Issue (issue) | New certificate requests |
Re-issue (reissue) | A fresh issuance with a new key — also of a certificate that is still active (key rotation, algorithm change, manual-DNS refresh) |
Renew (renew) | Manual renewals — the single renew action and the two other ways an operator could trigger one: bulk renew is refused to a gated operator (there is no bulk request; renew each certificate to raise one), and a per-certificate renewal-threshold change that would make the certificate due immediately is refused with a pointer to the renew action. |
Revoke (revoke) | Operator revocation at the CA — the whole certificate or one retained version. The request keeps the version and the reason, and approving it revokes exactly that. One open revoke request per certificate. |
Download (download) | Private-key export |
Supply-chain operations
| Operation | Default | Gates |
|---|---|---|
Configuration changes (config_edit) | All operators | Operator create / update / delete of an ActionSet, PathSet, project-variable, Target, TargetGroup, or ModuleConfig (including group member add / remove). Module credentials stay admin-only (they hold secrets); the module health-check stays admin. |
Distribution actions (distribute) | No approval | Operator distribution link / update / unlink / execute / rollback. |
Configuration changes are gated by default. These resources were previously admin-only — operators could not touch them at all. Their write routes were relaxed from admin-only to operator, so opening write access only through approval is a net-safe expansion.
Distribution actions are not gated by default. Operators already link and run distributions; gating them by default would break existing deploy flows.
Clusters during an upgrade
A node still running an older version does not know project policies: it keeps applying the organization-wide switches it reads from General settings (their last saved values, until a node on the new version saves General settings and drops them — after that the old node asks no operator for approval except for configuration changes, so finish the upgrade before saving General settings). Saving a policy is therefore refused with 409 CLUSTER_UPGRADE_REQUIRED — naming the nodes still to upgrade — until every node runs a version that supports it.
The distribute gate only covers the manual, operator-initiated action through the HTTP handler. The scheduler's automatic post-renewal distribution sweep bypasses the handler and is therefore not gated — gating it would block renewals from ever reaching their targets. A distribution that runs an ActionSet on SSH or WinRM targets needs the Admin role to execute or roll back by hand, and choosing a distribution's PathSet / ActionSet needs it too: an operator is refused (403) — unless this gate covers the operator, in which case the action becomes a request an admin approves.
Scheduler-driven auto-renewals are likewise not affected by the certificate-lifecycle gates — those gates sit on the API operations only.
Generic resource model
Originally every approval request referenced a certificate. With config_edit and distribute the request is generalised: an ApprovalRequest now carries resource_type / resource_id / resource_name so it can reference an action_set, path_set, variable, target, target_group, module_config, or distribution — not just a certificate. An empty resource_type (legacy rows) or certificate keeps the original cert-centric behaviour. For a create / link request where the object does not exist yet, resource_id is a sentinel new:<kind>:<name>.
The proposed change or action is stashed in the request's Params at submit time and replayed on Execute, exactly like the certificate flow. Two application shapes:
config_editapplies synchronously — Execute calls the target service's Create / Update / Delete directly; there is no job.distributeenqueues a job — Execute enqueues the distribution execute / rollback job and links its ID to the request.
Stale guard (RESOURCE_CONFLICT). A config_edit update / delete / member-op Execute is rejected with error code RESOURCE_CONFLICT if the live resource changed since the request was raised — its UpdatedAt no longer matches the value captured at submit time. Replaying a stale edit would clobber newer content (an admin's direct edit, or another approved change that landed first). It is not retryable; the requester must resubmit the edit. Only edits move a target's UpdatedAt: writes the system makes on its own — per-certificate deploy state after a distribution run, the removal of a deleted certificate's state — do not, so a deploy that runs between request and approval does not cause RESOURCE_CONFLICT.
Secret project-variable encryption. When a config_edit request carries a secret-flagged project variable, its value is envelope-encrypted inside the stashed Params — the secret is never at rest in plaintext in the approval record. Execute decrypts it back only inside the apply call's scope, and the variable service re-encrypts on save.
Certificate import / re-import activates and distributes a certificate without going through the approval workflow (deferring it would require persisting the uploaded private key in the approval record). To stop a non-privileged operator from using import to sidestep "require approval for issue," import and re-import require the Admin project role rather than operator.
Lifecycle
| Status | Meaning |
|---|---|
pending_approval | Awaiting a reviewer. |
approved | Accepted — waiting for an explicit Execute. |
executing | Operation in flight. |
executed | Ran successfully (job outcome tracked on the job itself). |
execution_failed | Operation errored; retryable failures can go back to approved. |
rejected | Declined, with an optional reason. |
cancelled | Withdrawn by the requester or an admin before execution. |
expired | Not completed within 7 days of creation. |
Only one open request may exist per resource + operation (certificate + op, or resource + op for config_edit / distribute) — a duplicate submit is rejected until the first request reaches a terminal state.
Who approves — and who bypasses
- Approve / reject requires the project admin role (or higher) on the request's project.
- Self-approval is blocked at the service layer — the approver cannot be the requester ("cannot approve your own request").
- Admins and owners bypass the gate: when a privileged user performs an operation the project gates for anyone, it runs immediately, and an approval record is written directly in
executedstatus (flaggedauto_executed, with themselves as requester and approver) so the approval history stays complete. No request, approval or Execute step is involved.
Net effect: the gate adds a second pair of eyes for operator-initiated actions; admin/owner bypass all approval (the operation runs directly and an auto-executed approval record is written) across every operation type — lifecycle, config_edit, and distribute alike.
Execution
Approval does not auto-run the operation. After a request reaches approved, the requester or a project admin clicks Execute (or calls the execute endpoint). The requester must still hold at least the operator role in the request's project at that moment — a requester who was demoted or removed from the project after approval is refused (403), for Execute, Retry and for consuming an approved download token; the request stays approved and a project admin can still execute it. Execution:
- enqueues the underlying job for issue / reissue / renew / revoke (the job ID is linked from the request), or
- mints a one-time download token for download requests, or
- applies the
config_editchange synchronously (Create / Update / Delete on the resource — no job), or - enqueues the distribution execute / rollback job for a
distributerequest.
For an issue request the certificate policy is evaluated again at this point (it may have been tightened while the request waited); a violation fails the execution with VALIDATION_ERROR and the violation codes, and moves the certificate to rejected.
If execution fails, the request lands in execution_failed with an error code. A certificate request (renew, reissue, revoke, download) whose certificate was revoked after it was approved can never run: Execute refuses it and closes it as execution_failed with CERTIFICATE_REVOKED (no Retry). The UI offers Retry for transient codes (JOB_QUEUE_ERROR, CA_ERROR, STATUS_CONFLICT); retry moves the request back to approved and executes again — no re-approval needed. RESOURCE_CONFLICT (a config_edit whose live resource changed since the request was raised) is not retryable — resubmit the edit against the current resource.
An issuance whose job could not be queued (JOB_QUEUE_ERROR) puts the certificate back into awaiting approval, so Retry runs it again; if an earlier attempt already moved it to pending without a job, Retry starts the missing job (or returns the one already running). Retry never issues twice: once the certificate's issuance has actually run — it recorded an error or an issuance, or already placed an order with the CA — Retry is refused with VALIDATION_ERROR; start a new issuance from the certificate page instead. When the licence's certificate limit is reached at execution, the request fails with VALIDATION_ERROR and the certificate moves to rejected — delete it and request again once a slot is free.
Expiry
Every request gets a fixed 7-day TTL at creation (not configurable). There is no background sweep — expiry is enforced lazily: any approve / reject / execute / cancel attempt on an overdue request atomically flips it to expired, emits approval.expired, and fails the attempted action. Expired requests never execute; re-submit if still needed.
Approved downloads
Private-key export through the gate ends in a token exchange rather than a direct file response:
- Requester asks to download in a format; a
downloadapproval request is created and keeps that format (and a JKS alias) — never a password (admins and owners download directly instead). - A project admin approves.
- Requester (or admin) executes — the response contains a raw download token.
- The browser fetches
GET /api/v1/downloads/{token}immediately and saves the file in the requested format. A PFX or JKS is sealed under a generated password, shown once; a request stored before the format was kept delivers every PEM part. An approved download always delivers the current version.
Token properties: 60-second TTL, single use (atomically consumed), bound to the executing user, and stored only as a SHA-256 hash. Expired, reused, or wrong-user tokens all fail identically. See Certificate download for formats.
Preflight warnings
Independent of the approval gates, MSCA issuance runs preflight checks and can pause submission with warnings that the requester must explicitly confirm (re-submit with the confirmation flag):
- template cache older than 30 days — consider syncing templates,
- connection not validated in over 24 hours,
- credentials changed after the last successful authentication.
Other issuer types skip preflight. The confirmation is part of the request, so approvers review a warned-and-acknowledged submission.
My Requests page
My Requests in the main navigation:
- My Requests view — everything you submitted, filterable by status (All / Pending / Approved / Rejected / Executed / Failed / Expired / Cancelled). Rows expand to show reason, reviewer, rejection comment, and execution errors.
- Pending Reviews view (project admins only) — every
pending_approvalrequest you can act on, with a live count badge.
Actions offered per status (the API additionally lets project admins execute / retry / cancel — see endpoints):
| Status | Requester (My Requests) | Project admin (Pending Reviews) |
|---|---|---|
pending_approval | Cancel | Approve · Reject · Cancel |
approved | Execute · Cancel | view only |
execution_failed | Retry (if retryable) + error detail | view only |
executed | Link to the resulting job | view only |
Notifications
Route these through notification rules:
| Event | Fires when |
|---|---|
approval.requested | A request enters pending_approval (admin/owner operations never raise one). |
approval.approved | A reviewer approves a request. |
approval.rejected | A reviewer rejects. |
approval.executed | Execution completed successfully. |
approval.expired | A stale request is flipped to expired. |
Payloads carry operation_type, the requester / reviewer display names, and either primary_domain (certificate requests) or resource_type + resource_name (config_edit / distribute requests) — see template variables.
API endpoints
All under /api/v1, authenticated. The action endpoints are rate-limited to 10 approval actions per user per minute.
| Method | Path | Who |
|---|---|---|
| GET | /approval-requests/my | Any user — own requests |
| GET | /approval-requests/:id | Any user in the org |
| POST | /approval-requests/:id/approve | Project admin (not the requester) |
| POST | /approval-requests/:id/reject | Project admin |
| POST | /approval-requests/:id/execute | Requester or project admin |
| POST | /approval-requests/:id/retry | Requester or project admin |
| POST | /approval-requests/:id/cancel | Requester or project admin |
| GET | /downloads/:token | Holder of a valid, unused token (user-bound) |
| GET | /projects/:projectId/approval-requests | Project admin — review queue |
| GET | /projects/:projectId/approval-policy | Any project member — the policy (default: true when none is saved) and me (whether the caller needs approval, per operation). The listed users and groups, with their names, are returned only to project admins and owners; anyone else gets empty lists and subjects_hidden: true, like the member roster |
| PUT | /projects/:projectId/approval-policy | Organization owner — body {rules: {<operation>: {mode, user_ids, group_ids}}, version} (version 0 when editing the defaults). 400 for an unknown operation or mode, selected without anyone, or a user or group without a role in the project; 409 RESOURCE_CONFLICT for a stale version; 409 CLUSTER_UPGRADE_REQUIRED while an older node is live |
| DELETE | /projects/:projectId/approval-policy | Organization owner — back to the defaults |
Troubleshooting
"an open request already exists for this certificate"
One open request per certificate + operation. Find it on My Requests and cancel or complete it first.
Approved, but nothing happened
Approval doesn't execute. Open My Requests, find the approved row, click Execute.
An operator is (or is not) asked for approval
Open Settings → Approvals in that project. The rule for the operation decides: No approval, All operators, or Selected operators — then the user must be listed or belong to a listed group. A user who has an admin role in the whole project, or an admin grant on the resource, is never asked; a user whose admin role is limited to granted resources is asked wherever it acts with its base role — when it creates something, for instance — and the page tells it so. Group membership changes apply on the next request. A user removed from the organization and a deleted group are removed from every policy, and so is a user or group whose roles are saved without a role in the project; a Selected operators rule left with nobody gates nobody. A listed subject that lost its role some other way shows as Former member and can be removed; it blocks nothing.
"cannot approve your own request"
Separation of duties — another project admin must review it. (Admins and owners never raise requests for their own gated operations — those run directly.)
Download token "expired" seconds after execute
The token lives 60 seconds and works once, for the user who executed. Execute again to mint a fresh token and let the browser follow it immediately.
See also
Video tutorials
Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →