Signals

Register a client certificate

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

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

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.

Authorization

bearer
headerAuthorizationBearer <JWT>

Request Body

application/json
  1. body
certificate*string

The client certificate, PEM. Only its first certificate is read; never send its private key.

Length1 <= length <= 16384

Response Body

The registered certificate. Location names it.

application/json
  1. response
sha256*string

SHA-256 fingerprint of the certificate, lowercase hex: its id here.

serialNumber*string
subject*string
notAfter*string

When the certificate expires, ISO 8601. After it, calls with it are refused.

registeredAt*string
Example Request
curl -X POST 'https://api.sandbox.ovok.com/v1/signals/certs' \  -H 'Content-Type: application/json' \  -d '{  "certificate": "string"}'
Example Response
{  "sha256": "string",  "serialNumber": "string",  "subject": "string",  "notAfter": "string",  "registeredAt": "string"}

List the project's client certificates GET

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 ```bash 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](/access-policies#who-can-call-a-route).

Issue a client certificate from a CSR POST

Issues a client certificate for your current project from a certificate signing request (CSR), and registers it. Calls into Signals may then present it, and must once `SIGNALS_MTLS_ENABLED` is on. **Auth:** A client credential cannot issue a certificate for itself. **Scope:** the caller's project (from the token). ## Behaviour - Make a key and a CSR on your side, and send the CSR as PEM in `csr`. The private key never leaves your client. - The key must be an EC key on P-256 or P-384 that names its curve, or an RSA key of at least 2048 bits, and the CSR's signature must verify. Otherwise 422 `CSR_NOT_ACCEPTED`, with the reason. - Ovok's CA signs a certificate for client authentication only, valid for six months, or until the CA itself expires if that comes first. Its `notAfter` is in the answer. Its subject is `CN=<tenant id>` and its subject alternative name `urn:ovok:signals-tenant:<tenant id>`. Nothing else in the CSR is taken over. - The certificate counts towards the project's two: a third answers 409 `CERTIFICATE_LIMIT_REACHED`. - An environment with no CA set up to issue answers 501 `FEATURE_NOT_CONFIGURED`. If its CA has expired, Ovok registers nothing and answers 500 `INTERNAL_ERROR`. - The answer is 201 with the registered certificate and its PEM in `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: issue a new certificate, move your clients to it, then remove the old one. ## Example ```bash openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -pkeyopt ec_param_enc:named_curve -nodes \ -keyout client.key -out client.csr -subj "/CN=client" curl -X POST 'https://api.sandbox.ovok.com/v1/signals/certs/issue' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d "{ \"csr\": $(jq -Rs . < client.csr) }" | jq -r .certificate > client.crt ``` **Who can call it:** a project admin. See [roles](/access-policies#who-can-call-a-route).