Back to RTB CA

RTB CA API

Static endpoint documentation for the public CA HTTP API. Each endpoint below includes what it does, a request example, and a response example.

Authentication

Endpoint Summary

Method Path What it does
GETPOST/api/v1/ca/pingLiveness probe
GET/api/v1/ca/statusRuntime status, config, and token state
POST/api/v1/ca/unsealCache the HSM PIN and import token material
POST/api/v1/ca/generateCreate a key, CSR, and signed certificate
GETPOST/api/v1/gen_user_certLegacy alias for generation
POST/api/v1/ca/signSign an incoming PEM CSR
POST/api/v1/ca/sign_sshSign an SSH public key
POST/api/v1/ca/sign_tsqSign an RFC 3161 timestamp query
GET/api/v1/certsList available CA and SSH signing material
GET/api/v1/certs/rootDownload the root certificate
GET/api/v1/certs/by_fingerprint/<fingerprint>Download a cert by SHA-256 fingerprint
GET/api/v1/certs/by_sn/<serial_number>Download by serial number
GET/api/v1/certs/by_label/<label>Download by label
GET/api/v1/logRead the audit log

GETPOST/api/v1/ca/ping

Simple liveness check. Use this when you only need to know whether the API process is reachable.

Request

curl https://test.pki.rtb-bl.de/api/v1/ca/ping

Response

pong

GET/api/v1/ca/status

Returns runtime status, token metadata, loaded config, hostname, and version information. On the real HSM-backed instance this can be slow because it enumerates PKCS#11 tokens.

Request

curl -H 'Authorization: Bearer <token>' \
  https://test.pki.rtb-bl.de/api/v1/ca/status

Response

{
  "hostname": "rtb-pki-12",
  "tokens": [
    {
      "serial": "DENK0104761",
      "label": "rtb_pki_root",
      "needs_pin": true
    }
  ],
  "config": {
    "oauth_client_id": "rtb-device-ca-web"
  }
}

POST/api/v1/ca/unseal

Unseals a token by caching its PIN and importing the token-backed certificates and policy objects.

Request

curl -X POST https://test.pki.rtb-bl.de/api/v1/ca/unseal \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "pin": "<hsm-pin>",
    "backend_id": "DENK0104761"
  }'

Response

{}

POST/api/v1/ca/generate

Generates a new keypair, creates a CSR, signs it with the selected CA, and returns the certificate bundle. The legacy alias /api/v1/gen_user_cert uses the same backend flow.

Request

curl -X POST https://test.pki.rtb-bl.de/api/v1/ca/generate \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "subject_cn": "device.example.test",
    "ca_name": "RTB Document Sign CA Test",
    "format": "pem"
  }'

Response

{
  "format": "pem",
  "filename": "1234567890.pem",
  "serial": 1234567890,
  "data": "-----BEGIN PRIVATE KEY-----\n...\n-----END CERTIFICATE-----\n"
}

GETPOST/api/v1/gen_user_cert

Legacy alias for /api/v1/ca/generate. Use the same payload and expect the same response shape.

Request

curl -X POST https://test.pki.rtb-bl.de/api/v1/gen_user_cert \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "subject_cn": "device.example.test",
    "ca_name": "RTB Document Sign CA Test"
  }'

Response

{
  "format": "pem",
  "filename": "1234567890.pem",
  "serial": 1234567890,
  "data": "-----BEGIN PRIVATE KEY-----\n...\n-----END CERTIFICATE-----\n"
}

POST/api/v1/ca/sign

Signs an incoming PEM CSR. Send either csr or csr_pem; the UI uses this for standard certificate signing.

Request

curl -X POST https://test.pki.rtb-bl.de/api/v1/ca/sign \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "ca_subject_cn": "RTB Document Sign CA Test",
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----\n"
  }'

Response

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

POST/api/v1/ca/sign_ssh

Signs an SSH public key with the configured SSH CA material. Accepts user_public_key or the legacy field public_key.

Request

curl -X POST https://test.pki.rtb-bl.de/api/v1/ca/sign_ssh \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cert_id": "my-laptop",
    "user_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... user@example",
    "principals": ["user@example"],
    "validity": "+8h"
  }'

Response

ssh-ed25519-cert-v01@openssh.com AAAAH... comment

POST/api/v1/ca/sign_tsq

Signs an RFC 3161 timestamp query. In local mode the frontend can send a JSON request and the backend converts it to a TSQ before signing.

Request

curl -X POST https://test.pki.rtb-bl.de/api/v1/ca/sign_tsq \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @request.tsq

Response

Content-Type: application/timestamp-reply

[binary DER timestamp reply bytes]

GET/api/v1/certs

Returns metadata for the CA and SSH signing material that the UI can present to the user.

Request

curl -H 'Authorization: Bearer <token>' \
  https://test.pki.rtb-bl.de/api/v1/certs

Response

[
  {
    "type": "x509",
    "label": "rtb-document-sign-im",
    "subject_cn": "RTB Document Sign CA Test",
    "can_sign": true
  }
]

GET/api/v1/certs/root and friends

These endpoints download certificate material directly. They are separate routes but behave the same way: the response is a file download, not JSON.

/api/v1/certs/root

curl -O https://test.pki.rtb-bl.de/api/v1/certs/root

/api/v1/certs/by_fingerprint/<fingerprint>

curl -O https://test.pki.rtb-bl.de/api/v1/certs/by_fingerprint/<sha256>

/api/v1/certs/by_sn/<serial_number>

curl -O https://test.pki.rtb-bl.de/api/v1/certs/by_sn/<serial>

/api/v1/certs/by_label/<label>

curl -O https://test.pki.rtb-bl.de/api/v1/certs/by_label/rtb-document-sign-im

Response is typically application/x-pem-file or a related download type depending on the query parameters.

GET/api/v1/log

Reads audit records from the log service through the CA frontend.

Request

curl -H 'Authorization: Bearer <token>' \
  https://test.pki.rtb-bl.de/api/v1/log

Response

[
  {
    "id": 1,
    "type": "csr_signed",
    "payload": "{...}"
  }
]

Notes