Skip to main content
2 video tutorials

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:

ModeWho 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.

Changed in 1.6.0

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:

OperationGates
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​

OperationDefaultGates
Configuration changes (config_edit)All operatorsOperator 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 approvalOperator 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.

Scheduler auto-deploy is NOT gated

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_edit applies synchronously — Execute calls the target service's Create / Update / Delete directly; there is no job.
  • distribute enqueues 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.

Import bypasses the approval gates

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​

StatusMeaning
pending_approvalAwaiting a reviewer.
approvedAccepted — waiting for an explicit Execute.
executingOperation in flight.
executedRan successfully (job outcome tracked on the job itself).
execution_failedOperation errored; retryable failures can go back to approved.
rejectedDeclined, with an optional reason.
cancelledWithdrawn by the requester or an admin before execution.
expiredNot 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 executed status (flagged auto_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_edit change synchronously (Create / Update / Delete on the resource — no job), or
  • enqueues the distribution execute / rollback job for a distribute request.

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:

  1. Requester asks to download in a format; a download approval request is created and keeps that format (and a JKS alias) — never a password (admins and owners download directly instead).
  2. A project admin approves.
  3. Requester (or admin) executes — the response contains a raw download token.
  4. 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_approval request you can act on, with a live count badge.

Actions offered per status (the API additionally lets project admins execute / retry / cancel — see endpoints):

StatusRequester (My Requests)Project admin (Pending Reviews)
pending_approvalCancelApprove · Reject · Cancel
approvedExecute · Cancelview only
execution_failedRetry (if retryable) + error detailview only
executedLink to the resulting jobview only

Notifications​

Route these through notification rules:

EventFires when
approval.requestedA request enters pending_approval (admin/owner operations never raise one).
approval.approvedA reviewer approves a request.
approval.rejectedA reviewer rejects.
approval.executedExecution completed successfully.
approval.expiredA 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.

MethodPathWho
GET/approval-requests/myAny user — own requests
GET/approval-requests/:idAny user in the org
POST/approval-requests/:id/approveProject admin (not the requester)
POST/approval-requests/:id/rejectProject admin
POST/approval-requests/:id/executeRequester or project admin
POST/approval-requests/:id/retryRequester or project admin
POST/approval-requests/:id/cancelRequester or project admin
GET/downloads/:tokenHolder of a valid, unused token (user-bound)
GET/projects/:projectId/approval-requestsProject admin — review queue
GET/projects/:projectId/approval-policyAny 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-policyOrganization 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-policyOrganization 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 →

Approvals for Issuing, Revoking and Private-Key DownloadsYouTube ↗
Approvals for Certificate Deployments (Four-Eyes Principle)YouTube ↗