Authenticating with the kycert API Using API Keys

Every request to the kycert API must include an API key. Keys are scoped to specific operations, tied to a single tenant (your brokerage), and can be revoked instantly from the dashboard. There is no OAuth flow — include your key in the X-API-Key header and you’re authenticated.

Creating an API key

Go to the API Keys page

In the kycert dashboard, navigate to Settings → Developer → API Keys.

Click New API Key

Click the New API Key button to open the key creation dialog.

Name the key

Enter a descriptive name that identifies where this key is used, for example Production Integration - ERP System or Onboarding Service - Staging. You’ll see this name in audit logs and the revocation list.

Select the environment

Choose Live for production requests or Sandbox for development and testing. This selection determines the key prefix and the data the key can access — you cannot switch a key between environments after creation.

Select scopes

Choose only the permissions your integration needs:

runs:write — create bureau runs
runs:read — read run status, decisions, and analysis
detail:read — access per-source technical detail (requires support approval)

For an automated onboarding flow that creates runs and receives results via webhook, runs:write alone is sufficient. Add runs:read if your service also polls run status or lists run history.

Copy and store the key immediately

Click Create. The full API key is shown once and never again. Copy it to your secrets manager or environment variables before closing the dialog. If you lose the key, revoke it and create a new one.

Using your key

Include the key in the X-API-Key header on every request:

curl -X POST https://admin.kycert.com.br/api/v1/bureau/runs \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "550e8400-e29b-41d4-a716-446655440000",
    "subject": {
      "type": "pf",
      "doc": "12345678901",
      "name": "João Silva"
    },
    "external_id": "cust_abc123"
  }'

Alternatively, pass the key as a Bearer token in the Authorization header. Both formats are accepted and equivalent — X-API-Key is recommended for simplicity:

curl -H "Authorization: Bearer sk_live_your_key_here" \
  https://admin.kycert.com.br/api/v1/bureau/runs

Key scopes

Each API key carries a set of scopes that restrict what it can do. Requests with a valid key but insufficient scope return 403 Forbidden.

Scope	Allows
`runs:write`	Create bureau runs (`POST /api/v1/bureau/runs`)
`runs:read`	Read run status and results (`GET /api/v1/bureau/runs`, `GET /api/v1/bureau/runs/:id`, `GET /api/v1/bureau/runs/:id/analysis`)
`detail:read`	Access per-source technical detail (`GET /api/v1/bureau/runs/:id/detail`) — requires support approval

Keys with no scopes are rejected. The system does not grant implicit access — every permitted operation must be explicitly listed in the key’s scopes.

Key prefixes

The key prefix tells you which environment a key targets:

Prefix	Environment	Uses
`sk_live_`	Production	Real bureau queries against live data sources
`sk_test_`	Sandbox	Fixture data — no credits consumed, no real queries

The API reads the prefix on each incoming request and routes it to the correct environment automatically. You do not manage environment routing — switching between sandbox and production is as simple as swapping the key.

Pinning an API version

Include the x-kycert-api-version header to pin your integration to a stable API version:

curl -H "X-API-Key: sk_live_your_key_here" \
     -H "x-kycert-api-version: 2026-06-03" \
     https://admin.kycert.com.br/api/v1/bureau/runs

Omitting the header uses the latest version, which may receive breaking changes. Pinned versions are maintained for at least 12 months after a deprecation notice.

Multi-tenant isolation

Each API key is bound to your tenant. You can only access runs, templates, and results that belong to your brokerage. Requests for resources owned by another tenant return 404 — not 403 — so your existence is not exposed to other tenants.

Revoking a key

Go to Settings → Developer → API Keys and click Revoke next to the key. Revocation is immediate — in-flight requests using the revoked key return 401 from that point forward. To rotate a key safely: create the new key, deploy the new key to your system, verify it works, then revoke the old key.

Security best practices

Store API keys as environment variables or in a secrets manager. Never hardcode a key in source code, commit it to a repository, or log it. A live key with runs:write scope can create bureau runs and consume your credits if exposed.Follow these practices for every key you create:

Least privilege — assign only the scopes the integration actually needs.
One key per service — create separate keys for each application, service, or deployment environment so you can revoke one without disrupting others.
Never use sk_live_ keys in development — always use a sk_test_ key for local development and staging.
Rotate regularly — treat key rotation as a routine operation, not an emergency response.

Auth error codes

HTTP status	Code	Meaning
`401`	`missing_api_key`	No `X-API-Key` header (or `Authorization: Bearer`) was provided
`401`	`invalid_api_key`	The key is revoked, inactive, or does not exist
`403`	`insufficient_scope`	The key is valid but lacks the required scope for this operation
`403`	`subject_type_not_allowed`	The key is restricted to PF or PJ but the request targets the other type

See Errors for the complete error code reference and retry guidance.

​Creating an API key

​Using your key

​Key scopes

​Key prefixes

​Pinning an API version

​Multi-tenant isolation

​Revoking a key

​Security best practices

​Auth error codes