OpciloSeal and verify
Verify

Developers

Client certificates for the Developer API

Client certificates are an advanced option alongside workspace API keys. Opcilo stores your public PEM and fingerprint only — your private key stays local.

Register in Developer console

← Developer API overview

When to use client certificates

Optional advanced auth for Business, Enterprise, or entitled custom workspaces that want certificate-bound access in addition to API keys.

Most partners integrate with API keys alone. When mTLS ingress is enabled on the Developer API host for your environment, present your registered client certificate on the TLS connection. API key headers may still be required depending on entitlement and route — follow OpenAPI and the partner guide for your deployment.

What you prepare locally

  • Generate or obtain a client certificate and matching private key (RSA or EC).
  • Keep the private key only on your side — HSM, secret store, or restricted file permissions. Opcilo never receives or stores your private key.
  • Export the public PEM you will register. Compute SHA-256 fingerprint as lowercase hex without colons (see OpenSSL snippet below).

Register in the Opcilo Developer console

  1. Step 1

    Sign in as a workspace admin with Developer entitlement.

  2. Step 2

    Open Developer → Certificates.

  3. Step 3

    Request a registration challenge (single-use, about 10 minutes).

  4. Step 4

    Submit your public PEM only (never the private key).

  5. Step 5

    Sign the canonical proof-of-possession payload with the private key that matches the PEM.

  6. Step 6

    Paste the Base64URL signature, set scopes, and Register.

Proof of possession (exact contract)

Registration uses two management calls with your workspace admin JWT: POST /api/developer/certificates/challenges, then POST /api/developer/certificates with name, publicPem, scopes, challengeId, and signatureBase64Url.

Sign the following UTF-8 payload with LF newlines and no trailing newline. expiresAt is the challenge expiry from step one (Unix seconds), not the certificate NotAfter. The challenge nonce is for your records and is not part of the signed bytes.

Algorithms: RSA-SHA256 PKCS#1 v1.5 or ECDSA-SHA256. ECDSA signatures may be DER (OpenSSL default) or IEEE P1363.

Canonical payload (LF newlines, no trailing newline)

opcilo-client-cert-register
v1
{challengeId}
{fingerprintSha256 lowercase hex}
{expiresAt unix seconds}

Copy-ready signing snippets (OpenSSL and PowerShell)

OpenSSL (RSA or EC private key)

CHALLENGE_ID="11111111-2222-3333-4444-555555555555"
FINGERPRINT="$(openssl x509 -in partner.crt -noout -fingerprint -sha256 | cut -d= -f2 | tr -d ':' | tr 'A-Z' 'a-z')"
EXPIRES_UNIX="1700000000"
printf 'opcilo-client-cert-register\nv1\n%s\n%s\n%s' "$CHALLENGE_ID" "$FINGERPRINT" "$EXPIRES_UNIX" > payload.txt
openssl dgst -sha256 -sign partner.key -out sig.bin payload.txt
openssl base64 -A -in sig.bin | tr '+/' '-_' | tr -d '='

PowerShell (RSA; EC variant noted in snippet)

$payload = "opcilo-client-cert-register`nv1`n$challengeId`n$fingerprint`n$expiresUnix"
$bytes = [Text.Encoding]::UTF8.GetBytes($payload)
$rsa = [Security.Cryptography.RSA]::Create()
$rsa.ImportFromPem((Get-Content .\partner.key -Raw))
$sig = $rsa.SignData($bytes, [Security.Cryptography.HashAlgorithmName]::SHA256, [Security.Cryptography.RSASignaturePadding]::Pkcs1)
$b64 = [Convert]::ToBase64String($sig).TrimEnd('=').Replace('+','-').Replace('/','_')
# For an EC key, use [Security.Cryptography.ECDsa]::Create(), ImportFromPem, and SignData with HashAlgorithmName.SHA256.

After registration — calling the API

When mTLS ingress is enabled on the Developer API host for your environment, configure your HTTP client to present the client certificate on the TLS handshake to that host.

Ingress and certificate requirements are environment-specific. Development and Production use separate credentials — do not reuse Dev keys or Dev client certificates on Production.

Revoke and re-register

Revoke a certificate in Developer → Certificates when a key is compromised or rotation is due. You can re-register the same public PEM with a new challenge after revocation.

Only one active registration may hold a given fingerprint at a time.

Do not

  • Send your private key to Opcilo — registration accepts public PEM only.
  • Do not commit private keys or signing secrets to git or ticket systems.
  • Reuse Development certificates or API keys on Production.

Related