REST API overview¶

Everything the dashboard does is available under /api/v1, and the Agent, the plugins and the reporting scripts use the same API. This page covers the conventions that apply to every call; the interactive reference lists each route.

Where the API lives¶

The ingest host is never filtered by the workspace IP allowlist; the workspace address is, unless Settings → Security allows ingest from any IP. Use the exact base URL shown on the Install Tokens, API Keys or Delegated DNS-01 page rather than deriving one.

Interactive reference¶

Sign in to your workspace and open API docs from the account menu, or go to /api/v1/docs (Swagger UI) or /api/v1/redoc; the schema is at /api/v1/openapi.json. The reference is generated from the running platform, so it always matches the deployed version. Demo accounts are redirected away from it. GET /api/v1/meta (no authentication) returns the product version, build, deployment mode and capability flags; GET /api/v1/version adds the database schema status.

Authentication¶

• API keys are presented as <prefix>.<secret> in either the X-Api-Key header or Authorization: Bearer <prefix>.<secret>. What a key may do is decided by its kind, its API role and its organization binding; see API keys & authentication. A wrong, revoked or expired key always gets the same 401. A read-only key (the API read-only role, or a custom API role that holds only read permissions) may only send GET requests under /api/v1; anything else answers 403.
• Browser sessions from the dashboard can call the API too (the API docs page relies on this). POST /api/v1/auth/login starts a session for a local account and is throttled like the sign-in page (10 attempts per minute per address and email, 30 per address, and a 15-minute lockout after eight consecutive failures); a spent limit answers 429 with Retry-After. Single sign-on users sign in through the dashboard.
• POST /api/v1/auth/change-password refuses a new password equal to the current one (400). Wrong current passwords have their own limit (eight per account in 15 minutes, then 429 with Retry-After) and do not count toward the sign-in lockout. For an account with two-factor sign-in, the answer has mfa_required: true and the session can only call POST /api/v1/auth/mfa/verify (with code or recovery_code), GET /api/v1/auth/me and POST /api/v1/auth/logout until the code is verified; every other call answers 403 with mfa-required.
• GET /api/v1/auth/me describes the current principal: the tenant, the organizations it can act in, its permissions, and for a reporting key the reporting_organization_id its submissions land in. It is the quickest way to check a new key.

curl https://<slug>.app.certin.tel/api/v1/auth/me \
  -H "X-Api-Key: cik_<prefix>.<secret>"

Pagination¶

List routes use keyset pagination:

Responses carry the rows in items and a meta object with limit, next_cursor and has_more; stop when has_more is false. A list refuses a query parameter it does not take with 422 (Unknown query parameter; this list takes: …) instead of answering an unfiltered list; there is no sort parameter. The interactive reference lists each route's filters.

Errors¶

Every error is an RFC 9457 problem document with Content-Type: application/problem+json:

{
  "type": "https://certin.tel/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "…",
  "request_id": "…",
  "errors": [{"field": "…", "message": "…"}]
}

errors appears only on validation failures (422). Text containing the NUL character (U+0000) or an unpaired UTF-16 surrogate - in the path, a query parameter, a JSON body or a form field - is refused before any route runs with a 422 whose error has "type": "invalid_character" and names the field (Text cannot contain the NUL character (U+0000) or an unpaired UTF-16 surrogate.). Quote the request_id when you report a problem; every 5xx answer carries one, in the body and the X-Request-Id header. A resource that exists in another tenant or organization answers 404, never 403, so an id cannot reveal what exists elsewhere; see troubleshooting. When a workspace accepts agents only on its own address (Only accept agent submissions on our workspace address under Settings → Security), an agent route called with that workspace's credential on any other address, such as the shared ingest host, answers 404 with the type …/problems/workspace-address-required and a detail naming the workspace address: This workspace accepts agents only on its own address, https://…. Enrol the agent again with that address, or turn off "Only accept agent submissions on our workspace address" on the workspace's Security page. Only a caller that already authenticated as that workspace gets this answer; see troubleshooting. A 429 (…/problems/rate-limited) carries a Retry-After header: the seconds left in the limit's window, rounded up (at least 1, never more than the window). Wait that long before retrying; a request sent after exactly that wait falls in the next window. Besides sign-in and ingest, the actions started by hand that send or probe something are limited: a destination's test (3 per destination and 10 per person a minute), a report's send and re-send (3 per report and 10 per person an hour) and an endpoint's check (3 per endpoint and 30 per person a minute). The person's limit is counted first and the detail says which limit refused the request; see Alerts & notifications.

Resource families¶

POST /api/v1/notification-channels/destinations/{id}/send-digest sends an alert destination everything that is open for it now, labelled as sent on request (see Send digest now). The destination's scheduled alerts and daily summary are not changed. It answers status sent, failed or nothing_due (nothing was sent), with tier, items, response_status and failure_class. It needs notifications.test and certificates.read in the destination's whole scope, answers 409 for a paused destination, and is limited like a test send (429 with Retry-After).

POST /api/v1/targets takes hostname as a DNS name or IP address only; the port goes in port. A URL is refused with 422, and the message names what to send: hostname must be a DNS name or IP address such as example.com, without https://, a port or a path (the port goes in port). For https://www.example.com:8443/shop, send hostname www.example.com and port 8443. The dashboard's Add a site form takes a pasted URL itself (see What to do first).

Workflows¶

A workflow is a certificate, the bundled template that installs it, and the Agents allowed to run it: one (the server the certificate is for) or up to 20 of one organization, first preferred. It is what Workflow Assignments in the dashboard lists and what New workflow creates. Errors are problem documents; a workflow or an Agent key outside the organizations the caller can act in answers 404.

The built-in roles: Observer and Auditor read; Operator creates, edits, moves and cancels; deleting needs Administrator. A read-only API key reaches the two GET routes only.

The proposal fields are those the workflow form fills in:

name is optional, at most 120 characters; left out, the workflow takes the certificate's name, or its id. api_key_ids lists 1 to 20 Agent keys of one organization, first preferred; a key listed twice is 422. A field the Agent does not report support for is refused with 422.

A workflow reads back with id, organization_id, name, certificate_id, state, api_key_ids, the proposal fields, bound_api_key_id (the Agent that runs it), offered_api_key_id and current_assignment_id (the proposal that is out), round_started_at, created_by, created_at and updated_at.

• List is paged like the other lists. state filters on one of the four states; api_key_id returns the workflows that name that Agent.
• Read one adds agents, offers and timeline. Each of agents has api_key_id, name, position, status (offered, running, tried or waiting) and problem: why that Agent cannot take the workflow now, or null. offers are the workflow's assignments, newest first.
• Create offers the workflow to its first Agent as a pending assignment; nothing is applied by the call. With several Agents, every one must be able to run the workflow now, or the answer is 422 and names each one that cannot. With one Agent the refusal is that Agent's own: 409 when it has sent no capabilities report, its credential cannot take proposals or the certificate id is taken there; 403 for an issuer the key may not use; 422 for the proposal itself.

• Edit (PUT) replaces the name, the Agents and the proposal. The certificate id cannot change (422). The answer adds outcome:

  outcome	What happened
  saved	Stored; nothing was sent.
  resent	The proposal that is out was sent again with the edit.
  offered	The workflow was offered afresh.
  exhausted	No Agent can take it now.
  update	Sent to the Agent that runs it, as a replacement it applies once approved there (Agent 1.8.2 or later).

  It is refused with 409 while the Agent is applying the workflow, and for a cancelled workflow. - Next withdraws the proposal that is out and offers the workflow to the next Agent that can take it; 409 unless a proposal is waiting. When nobody is left, the state is exhausted. - Restart starts a new round with the first Agent that can take it, or sends the workflow to the Agent named in api_key_id (404 when that key is not one of the workflow's Agents, 422 when it cannot run the workflow now). This is how a proposal the Agent rejected is sent again. A workflow an Agent runs moves to another Agent; the Agent that ran it keeps its copy until a local administrator removes it there. 409 for a cancelled workflow. - Cancel withdraws the proposal that is out. An Agent that already runs the workflow is also asked to remove it (Agent 1.19.0+; see Removing a workflow from the Agent). remove_from_agent omitted: removed from each Agent that can take a removal; an older Agent keeps it until a local administrator removes it there. true: 422 Requires Agent 1.19.0 or later on when the Agent is older. false: the Agent keeps it. - Delete is refused with 409 while a proposal is out; a removal that is out does not block it. remove_from_agent works as for Cancel. The workflow's assignments and activity events are kept. - A removal is listed among the workflow's assignments with request_type retire; other assignments have create or replace.

Workflow assignments¶

An assignment is one proposal of a workflow to one Agent. Every assignment has workflow_id.

• POST /api/v1/workflow-assignments takes the proposal fields and one api_key_id. It creates a workflow for that Agent, named after the certificate, and answers with its assignment.
• POST …/{id}/resend sends a waiting proposal again as a new revision. With a body (the proposal fields) it edits the workflow; the certificate id cannot change. A proposal the Agent rejected is not sent again here (409): restart its workflow with POST /api/v1/workflows/{id}/restart.
• POST …/{id}/cancel withdraws a waiting proposal. Its workflow goes to the next Agent, or is left exhausted when there is none.
• DELETE …/{id} removes a finished assignment. Its workflow stays.

Routes used only by the platform console are not part of the published schema.