API access: issue your own API keys

Use the Settings → API access screen to mint, list, rotate, and revoke API credentials for your firm. Each credential authenticates against the Certivus Partner API the same way an external integrator (such as Hirenza) would. The only difference is that the firm context is implicit, so you don't need to pass external_account_id on every call.

Who can use this

• API access and white-label branding are available only on Custom (Enterprise), a bespoke plan. Contact sales to arrange access; Starter, Professional, and Scale do not include them.
• Only firm-owners can mint, rotate, or revoke credentials. Managers and staff can't see this screen.

Creating a credential

1. Click New credential.
2. Give it a label that names the integration, e.g. "Internal dashboard", "CI pipeline", or "Custom CRM sync". The label is for your reference only; it shows up in your audit logs but never in API responses.
3. Pick the environment:
   • Production: live data. Audit logs tag the credential as production-traffic.
   • Sandbox: same endpoints, but audit logs filter to "test traffic." Useful when you want a separate credential for staging deployments.
4. Pick the scopes you need. Self-serve credentials are limited to:
   • cases:read / cases:write: list, fetch, and create verification cases
   • clients:read / clients:write: manage client records
   • passes:read: read Certivus Pass records shared with your firm
   • access:read / access:write: view and revoke Pass access shares
   • catalogue:read: read the checks and products catalogue
5. Click Create credential. The next screen shows the client_id and the client_secret. Copy both immediately. The secret is shown exactly once; Certivus never stores it in plaintext.

Using your credential

Exchange the client_id + client_secret for a 15-minute access token:

curl -X POST https://api.certivus.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "cv_self_…",
    "client_secret": "…",
    "grant_type": "client_credentials"
  }'

Then call any v1 endpoint with Authorization: Bearer <token>. For self-serve credentials, you don't need to pass external_account_id; Certivus resolves the firm from the credential itself.

Rotating a credential

Best-practice security says you should rotate API secrets periodically (every 90 days is a typical rhythm, more often after any team change).

1. Find the credential in the list, click the ⋮ menu, choose Rotate.
2. Pick the sunset window: how long the old secret keeps working. The default is 7 days (168 hours), which is enough time for most teams to roll the new secret into all the places they use it. The maximum is 30 days.
3. Click Rotate. A new credential is created and the old one is marked Sunsetting until …. The list now shows both; both authenticate during the overlap. The old one stops working when the sunset window expires.

During the sunset window:

• Update every integration that uses the old credential with the new client_id + client_secret.
• Watch your monitoring for any traffic still using the old client_id; that's an integration you missed.
• When you're sure nothing's still using the old one, you can revoke it early.

Revoking a credential

Use Revoke when:

• A credential has been compromised (leaked into a public repo, stolen laptop, ex-employee).
• You're decommissioning an integration permanently.

1. Click ⋮ → Revoke.
2. Type a brief reason; this goes into your audit log and is helpful when you (or auditors) read the trail months later.
3. Click Revoke credential.

The credential stops authenticating immediately. Any integration still using it will receive HTTP 401 errors on the next call.

Security best-practices

• Never commit secrets to source control. Use a secrets manager (1Password, AWS Secrets Manager, GitHub Secrets, Vercel Project Settings, etc.).
• One credential per integration. Don't reuse the same client_id across the CRM, the CI pipeline, and the internal dashboard. Separate credentials make it easy to revoke a single integration without breaking others.
• Rotate on schedule. A 90-day rotation cadence is industry-standard. Calendar reminders work.
• Rotate on personnel change. If someone with access to your secrets manager leaves the team, rotate.
• Watch the last_used_at column. A credential that hasn't been used in 30+ days is probably orphaned; consider revoking it.

What if I'm also working with a partner (e.g. Hirenza)?

Your firm-issued credentials and the partner's credentials are independent. Hirenza can keep calling Certivus on your behalf with their own credential while you simultaneously call the API directly with yours. Both paths produce audit-log entries with the right actor_partner_id so you can always tell who did what.

If you ever want to disconnect from a partner, you don't lose your firm: your credentials, audit log, and data all stay. Use Settings → Integrations (separate screen) to manage which partners are mapped to your firm.

Troubleshooting

• "Self-serve API keys" paywall → API access requires Custom (Enterprise). Contact sales to arrange access.
• HTTP 401 from /v1/auth/token → check the client_id is exactly as shown (the dashboard masks middle characters; copy from the rotation/generate dialog if unsure), and confirm the credential isn't revoked or past its sunset window.
• HTTP 402 ENTITLEMENT_REQUIRED → the requested capability is not enabled for your firm. API access requires Custom (Enterprise); contact sales to confirm your agreed access.
• A scope you wanted is missing: webhook scopes (webhooks:read, webhooks:write) and a few other advanced scopes aren't in the self-serve allowlist. Contact support to request them; they need a separate review.

Related

• Compliance Pack: what the API returns when you call GET /v1/cases/{id} or GET /v1/cases/{id}/pdf
• Audit log: see every API call that touched your firm's data