- Overview
- Reference Guide
- Setup & Architecture
- Release Notes
- Workflow
- API Reference
- Integration Guide
- Discovery Agent Setup Guide
Tasks
The Tasks endpoints list and delete the background tasks created by certificate operations, and approve or deny certificate requests that are waiting for approval.
For the corresponding user interface, refer to the Utilities > Tasks section.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /approve_request | Approve a certificate request. |
| GET | /deny_request | Deny a certificate request. |
| GET | /tasks | List or read workflow tasks. |
| DELETE | /tasks | Delete workflow tasks. |
| POST | /tasks/{taskID}/retrigger | Re-run one failed task, or the failed children of a bulk one. |
GET /approve_request
Records the signed-in approver's approval of a pending certificate request. This is the action behind the Approve link of the approval request e-mail: the approver must still be signed in, and must hold the Manage Certificate Requests administrator permission. Despite being a GET, it changes state. Issuance starts only once the number of approvals the request needs has been reached; until then the request stays pending. An approver who has already approved or denied this request gets 409 {"Error": "User action already noted"}, an EnrollmentID that is not a whole number gets 400, and an unexpected failure while processing gets 500 {"Error": "Could not approve certificate"}. (Until 2026-10-26 the last two and the 409 were answered 200 with an Error body.)
Request Parameters
| Name | Located In | Type | Required | Description |
|---|---|---|---|---|
EnrollmentID |
Query | string | Yes | Numeric ID of a certificate request that is awaiting approval (status requested), as a string of digits. Take it from the enrollment list. Anything that is not a whole number is a 400; a request that is not awaiting approval, or does not exist, answers 404. |
Example Request
curl -X GET "https://<certsecure-backend-url>/approve_request?EnrollmentID=<EnrollmentID>" \
-H "Authorization: Bearer <token>"Responses
| Status Code | Description |
|---|---|
| 200 | The approval was recorded. |
| 400 | The EnrollmentID query parameter was not supplied, or is not a whole number. |
| 401 | Authentication failed. The Authorization header is missing, malformed, expired, revoked, or names a session that no longer exists. |
| 403 | The caller does not hold the Manage Certificate Requests permission. |
| 404 | No request with this ID is awaiting approval. |
| 409 | The signed-in approver has already approved or denied this request. |
| 500 | Unhandled server-side failure. |
Example Response
{
"Success": "Certificate Approved"
}GET /deny_request
Records the signed-in approver's refusal of a pending certificate request. This is the action behind the Deny link of the approval request e-mail: the approver must still be signed in, and must hold the Manage Certificate Requests administrator permission. Despite being a GET, it changes state. One refusal does not necessarily end the request: it is marked denied (and the requester notified) only once approvals plus refusals have reached the number of approvers the estate has. An approver who has already approved or denied this request gets 409 {"Error": "User action already noted"}, an EnrollmentID that is not a whole number gets 400, and an unexpected failure while processing gets 500 {"Error": "Could not deny certificate"}. (Until 2026-10-26 these were answered 200 with an Error body, and the failure text said "Could not approve certificate".) Success means the refusal was recorded, not necessarily that the request is now denied: see above.
Request Parameters
| Name | Located In | Type | Required | Description |
|---|---|---|---|---|
EnrollmentID |
Query | string | Yes | Numeric ID of a certificate request that is awaiting approval (status requested), as a string of digits. Take it from the enrollment list. Anything that is not a whole number is a 400; a request that is not awaiting approval, or does not exist, answers 404. |
Example Request
curl -X GET "https://<certsecure-backend-url>/deny_request?EnrollmentID=<EnrollmentID>" \
-H "Authorization: Bearer <token>"Responses
| Status Code | Description |
|---|---|
| 200 | The refusal was recorded. |
| 400 | The EnrollmentID query parameter was not supplied, or is not a whole number. |
| 401 | Authentication failed. The Authorization header is missing, malformed, expired, revoked, or names a session that no longer exists. |
| 403 | The caller does not hold the Manage Certificate Requests permission. |
| 404 | No request with this ID is awaiting approval. |
| 409 | The signed-in approver has already approved or denied this request. |
| 500 | Unhandled server-side failure. |
Example Response
{
"Success": "Certificate Request Denied"
}GET /tasks
Without taskID, returns one page of the caller's tasks, most recently updated first, as a JSON array (empty when there are none). With taskID, returns that one task as a JSON object, or 404 when the caller has no such task. The internal job payload (task) is left out of every item.
Note: Call this endpoint without a trailing slash (/tasks). The Swagger API lists it as /tasks/.
Request Parameters
| Name | Located In | Type | Required | Description |
|---|---|---|---|---|
count |
Query | integer | No | Tasks per page, a positive integer (default 20); anything else is a 400. Pagination is applied whenever either count or page is supplied; the other one then takes its default. A value above 2147483647 is read as 2147483647. Ignored when taskID is supplied. |
format |
Query | string | No | Shape of the list answer. page opts in to an envelope, {data, total, page, count}, where total is the number of tasks matching the filters (what a client needs to paginate a filtered list). Any other value, or none, keeps the bare JSON array. Ignored when taskID is supplied. |
page |
Query | integer | No | One-based page number (default 1). Must be a positive integer; a value below 1 or one that is not an integer is a 400. A value above 2147483647 is read as 2147483647. Ignored when taskID is supplied. |
scope |
Query | string | No | Whose tasks to act on: mine (the default) or all; any other value is read as mine. all is honoured only for a caller who may manage every task, and is quietly narrowed to mine otherwise rather than refused — the console sends the last-used scope and a role change must not turn that into an error. |
status |
Query | string | No | Only tasks whose statusInfo equals this value: INITIALIZED, PROCESSING, OK or ERROR, matched without regard to case. An empty value filters nothing. Anything else is refused with 400. The inventory states (active, expired, revoked) and the request-workflow ones (pending, approved, denied) are not task statuses and are refused too. A task can carry a statusInfo outside this list; the filter cannot select those. Checked before taskID is looked at, so a bad value fails a single-task read as well. |
taskID |
Query | string | No | Identifier of one task to read, as returned when the task was created. When supplied, count and page are ignored and a single task object is returned instead of a list. |
Example Request
curl -X GET "https://<certsecure-backend-url>/tasks" \
-H "Authorization: Bearer <token>"Responses
| Status Code | Description |
|---|---|
| 200 | A JSON array of tasks, or -- when taskID was supplied -- a single task object. |
| 400 | The request was rejected as malformed or failed validation. |
| 401 | Authentication failed. The Authorization header is missing, malformed, expired, revoked, or names a session that no longer exists. |
| 404 | Only when taskID was supplied: the caller has no task with that identifier. |
Example Response
[
{
"TaskID": "10477",
"taskName": "Certificate Request",
"status": "Pending Approval by Admin",
"statusInfo": "PENDING",
"details": "Certificate has to be approved by: 1 Approver",
"createdOn": "2026-10-12 14:45:36",
"updatedOn": "2026-10-12 14:46:04",
"IP": "203.0.113.10",
"user": "[email protected]"
}
]DELETE /tasks
Queues the deletion of the listed tasks (the caller's own only) and returns immediately; the removal happens in the background, so a task may still appear in a GET for a moment afterwards. The answer is the same whether or not the identifiers exist. The body must be a JSON object sent with a JSON Content-Type (any other type is treated as missing, 400) and taskIDs a non-empty array of strings (400 otherwise).
Note: Call this endpoint without a trailing slash (/tasks). The Swagger API lists it as /tasks/.
Request Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
taskIDs |
array of string | Yes | Identifiers of the tasks to delete: a non-empty array of non-blank strings; anything else is a 400. Ones that do not exist, or belong to another user, are skipped without any error. |
Example Request
curl -X DELETE "https://<certsecure-backend-url>/tasks" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"taskIDs":["10478","10479"]}'Responses
| Status Code | Description |
|---|---|
| 200 | The deletion was queued. |
| 400 | The body is not a JSON object, or taskIDs is missing or not a non-empty array of strings. |
| 401 | Authentication failed. The Authorization header is missing, malformed, expired, revoked, or names a session that no longer exists. |
Example Response
{
"Message": "Task Initiated"
}POST /tasks/{taskID}/retrigger
This is what replaced the automatic 3x retry (see the NO AUTOMATIC RETRIES note in classes/functions/agentTaskQueue.py): every attempt at a public CA creates a real order and redeems a real credit, so the decision to make another one belongs to a person who can see the failure reason. Body (all optional): children: true -- re-run the failed SUB-tasks of a bulk task force: true -- proceed even though the CA could not be asked whether an order already exists. Never implied: "could not ask" is not "nothing there".
Request Parameters
| Name | Located In | Type | Required | Description |
|---|---|---|---|---|
taskID |
Path | string | Yes | ID of the failed task to re-run, as listed by GET /tasks. |
Request Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
children |
boolean | No | Re-run the failed SUB-tasks of a bulk task rather than the bulk task itself. |
force |
boolean | No | Proceed even though the CA could not be asked whether the original order is still live. ⚠️ Without a live check a re-run can place a second order for a certificate the CA is already issuing. |
Example Request
curl -X POST "https://<certsecure-backend-url>/tasks/<taskID>/retrigger" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"children":true,"force":false}'Responses
| Status Code | Description |
|---|---|
| 200 | Successful response. |
| 401 | Authentication failed. The Authorization header is missing, malformed, expired, revoked, or names a session that no longer exists. |