Skip to content

How-To: Troubleshoot API Errors

Find the step of a signing or certificate workflow that failed, and why, from the HTTP status code the Keyserver returned. Status meanings and the error body are in the Error Codes Reference.

Read the reason in the error body before anything else: properties[].message, or detail when properties is empty. See Error response format.

Signing workflow

flowchart TD
    A["Request an access token"] --> A1{"Token issued?"}
    A1 -- "no" --> AX["No token"]
    A1 -- "yes" --> B["POST /api/operations"]
    B -- "error" --> BX["401 Not authenticated<br/>403 No createoperation<br/>400 Malformed request<br/>404 Unknown or revoked keyid<br/>409 Key not initialized or listed twice"]
    B -- "201" --> C{"Operation approved?"}
    C -- "no" --> C1["Approver approves<br/>on the Approvals page"]
    C1 -- "error" --> CX["409 Approval refused<br/>410 Gone"]
    C1 --> C
    C -- "yes" --> D["POST /api/signorders"]
    D -- "error" --> DX["409 Conflict<br/>404 Unknown operation or key<br/>403 No order permission<br/>410 Gone<br/>400 Malformed request"]
    D -- "201" --> E{"Signature verifies?"}
    E -- "no" --> EX["Wrong hash algorithm"]
    E -- "yes" --> F["Signed"]

Diagram: Request an access token; Token issued?; no; No token; yes; POST /api/operations; error; 401 Not authenticated 403 No createoperation 400 Malformed request 404 Unknown or revoked keyid 409 Key not initialized or listed twice; 201; Operation approved?; Approver approves on the Approvals page; 409 Approval refused 410 Gone; POST /api/signorders; 409 Conflict 404 Unknown operation or key 403 No order permission 410 Gone 400 Malformed request; Signature verifies?; Wrong hash algorithm; Signed

Step Result Cause Reference
Request an access token No token Wrong client credentials or authorization server URL. The Keyserver is not involved yet Authentication Model
POST /api/operations 401 Not authenticated Diagnosing 401 vs 404 vs 403
403 No createoperation on a key Creating an operation
400 Malformed request Creating an operation
404 Unknown or revoked keyid Creating an operation
409 Key not initialized, or listed twice Creating an operation
Approval 409 Approval refused Status codes
410 Operation cancelled, or a key in it revoked Status codes
POST /api/signorders 409 Not approved, usage exhausted, not the creator, not a FW key, or a key not initialized Signing
404 Unknown operation or key, or key not in the operation Signing
403 No order on every key in the operation Signing
410 Operation expired or cancelled, or a key revoked Signing
400 Malformed request Signing
Verify the signature 201, but the signature does not verify Hash not made with the key's hash algorithm Signing

While the operation waits for approval, GET /api/operations/{id} returns approved: false. How approvers find and approve operations is in The approval workflow.

Certificate workflow

Authentication, operation creation and approval fail as in the signing workflow. The operation names a CA key.

flowchart TD
    A["Operation approved<br/>see Signing workflow"] --> B["POST /api/certificates"]
    B -- "error" --> BX["409 Conflict<br/>404 Unknown operation or key<br/>403 No createcertificate<br/>410 Gone<br/>400 Malformed request"]
    B -- "200" --> C["Certificate issued"]

Diagram: Operation approved see Signing workflow; POST /api/certificates; error; 409 Conflict 404 Unknown operation or key 403 No createcertificate 410 Gone 400 Malformed request; 200; Certificate issued

Result Cause Reference
409 Not approved, usage exhausted, not the creator, not a CA key, or a key not initialized Certificate issuance
404 Unknown operation or key, or key not in the operation Certificate issuance
403 No createcertificate on every key in the operation Certificate issuance
410 Operation expired or cancelled, or a key revoked Certificate issuance
400 Malformed csrpem or serialnumber Certificate issuance

Diagnosing 401 vs 404 vs 403

The status tells you which layer rejected you: the token, the subject registration, or the permissions. 401 has two forms, told apart by the detail text.

401 (ordinary): the token itself is the problem. The Keyserver could not validate it. Check, in order:

  1. Is the token present in Authorization: Bearer <token>?
  2. Has the token expired? Tokens are short-lived; fetch a fresh one per pipeline run.
  3. Does the aud claim match the Keyserver's configured audience?
  4. Was it issued by the configured identity provider?

401 "The user/client is not valid": the token is valid, but no registered subject matches it. A new client with a mismatched ID gets this 401 on every call, which is easy to misread as a credentials problem. Check:

  1. Does a subject exist whose Subject ID matches the token's identity claim? Copy the claim's value as issued rather than retyping it. For clients, a Subject ID ending in * matches any identity that starts with the text before the *, ignoring case; user logins do not use wildcards. On a user's first login, the username claim (such as preferred_username) is matched against the Subject name instead.
  2. Was the subject deleted? Deletion renames the subject, so the token no longer matches it. See Manage Subjects in the Keyserver.

Reading the claim without external tooling

In the Keyserver UI, the About page's "View ID Token" and "View Access Token" links decode the token's claims; compare sub/oid (users) or the client identity claim with the registered Subject ID. Client-credentials clients have no UI session, so decode their access token payload locally, for example with jq.

404: an unknown resource, not a subject problem. The subject was recognized, but the keyid, operation ID or datastore entry in the request does not exist, the key is not part of the operation, or the datastore entry was deleted. POST /api/operations also returns 404 for a revoked keyid. Check the identifier in the request against what exists.

403 "Access forbidden": the subject is recognized, and permissions are the problem. Check, in order:

  1. Does the subject have a role granting the API being called (for example order or createoperation)?
  2. Is the permission scoped to the specific key in the request? order on fw-quickstart does not grant order on a different key.
  3. Is the subject registered but role-less? A subject with no key-scoped permissions gets 403 from GET /api/keys itself.
  4. Was the token issued by the CI/CD authorization server? The pipeline endpoints (operations, sign orders, certificates, keys, datastore) refuse a token from the administrative identity provider with 403 "Authorization error" ("Authentication by CI/CD authorization server is required for method ...").

A request against an operation that another client created with creatorowns: true (the default) is refused with 409; only the creator may use it.