Signals

List the project's client certificates

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
GET
/v1/signals/certs

Lists the client certificates registered for your current project. With SIGNALS_MTLS_ENABLED on, every call into Signals through /v1/signals/api/* must present one of them.

Auth: A client credential cannot read or change them. Scope: the caller's project (from the token).

Behaviour

  • Each certificate is known by sha256, its SHA-256 fingerprint in lowercase hex. Ovok never holds a private key.
  • A project holds at most two: the one in use and one to rotate to.
  • A certificate past notAfter stays listed until it is removed, but calls presenting it are refused.
  • environment says what this Ovok environment can do: issues (a CA to issue from a CSR), registers (a CA it trusts for registration) and forwardsCertificates (an edge that passes client certificates on, which SIGNALS_MTLS_ENABLED needs). Check it before offering an action that would answer 501 or 409.
  • environment.caCertificate is the CA Ovok issues from, PEM, or null where it issues none.
  • With SIGNALS_MTLS_ENABLED on, Signals presents its own client certificate on every webhook delivery to your https endpoints. The certificate chains to that CA and carries the subject alternative name urn:ovok:signals:<environment>.
  • To accept only Signals, verify the client certificate against caCertificate and pin that name. Your project's own client certificates chain to the same CA, so the CA alone is not enough.
  • Keep verifying the webhook-signature too. With the setting off, deliveries carry no client certificate.
  • A project without a Signals tenant of its own answers 409 SIGNALS_TENANT_NOT_OWN.

Example

curl 'https://api.sandbox.ovok.com/v1/signals/certs' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

Who can call it: a project admin. See roles.

Authorization

bearer
headerAuthorizationBearer <JWT>

Response Body

The registered certificates, at most two, and what this environment can do for them. Never a private key.

application/json
  1. response
certificates*array<>
environment*
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/signals/certs'
Example Response
{  "certificates": [    {      "sha256": "string",      "serialNumber": "string",      "subject": "string",      "notAfter": "string",      "registeredAt": "string"    }  ],  "environment": {    "issues": true,    "registers": true,    "forwardsCertificates": true,    "caCertificate": "string"  }}

Register a client certificate POST

Registers a client certificate for your current project. Calls into Signals may then present it, and must once `SIGNALS_MTLS_ENABLED` is on. **Auth:** A client credential cannot register a certificate for itself. **Scope:** the caller's project (from the token). ## Behaviour - Send the certificate as PEM in `certificate`. Only its first certificate is read. Never send the private key: it stays with your client. - The certificate must be valid now, not a CA certificate, for client authentication (or have no extended key usage), and issued by a CA your Ovok environment trusts. Otherwise 422 `CERTIFICATE_NOT_ACCEPTED`, with the reason. - An environment with no CA set up for client certificates answers 501 `FEATURE_NOT_CONFIGURED`. - The same certificate twice answers 409 `CERTIFICATE_ALREADY_REGISTERED`; a third certificate 409 `CERTIFICATE_LIMIT_REACHED`. - The answer is 201 with the registered certificate, and `Location` names it. - At 00:00 UTC, 14 days before the certificate expires, Ovok notifies the project's admins in the Console and mails them and its parent project's admins. A certificate registered closer to its expiry is mailed about at once; a removed one is not. - To rotate: register the new certificate, move your clients to it, then remove the old one. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/signals/certs' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d "{ \"certificate\": $(jq -Rs . < client.crt) }" ``` **Who can call it:** a project admin. See [roles](/access-policies#who-can-call-a-route).