Authentication

Every Rekomi API call needs a bearer key. Some calls (S2S tracking, webhook delivery) need an additional HMAC signature with a separate signing secret. This page covers both.

Generate an API key

/dashboard/settings/api-keys. Click "New key".

Required:

• Name: human-readable label like "Vercel production" or "data warehouse sync".
• Scope: read (GETs only) or read_write (full access).

Click Create. Two values appear in a modal, shown EXACTLY ONCE:

• Plaintext bearer: starts with rk_live_ (production) or rk_test_ (staging). 32 random bytes, base64url-encoded. Copy now.
• Plaintext signing secret: starts with rks_. 32 random bytes. Used for HMAC on S2S endpoints. Copy now.

After you close the modal, the plaintext values are unrecoverable. The bearer is stored as a SHA-256 hash on our side. The signing secret is encrypted at rest using AES-256 with a key from the EF Core-backed Data Protection keyring.

If you lose your keys, rotate (below) or revoke and create new ones.

Use the bearer

Set the Authorization header on every request:

GET /api/v1/programs
Authorization: Bearer rk_live_xxxxxxxxxxxxxxxxxxxxx

The bearer identifies your organization. We do not require a separate X-Org-ID header; the bearer encodes everything we need.

Scopes

Two scopes:

• read: GET endpoints only. Cannot create, update, or delete resources. Cannot trigger payouts. Cannot rotate keys.
• read_write: full access to GET, POST, PATCH, DELETE. Subject to per-endpoint role checks (some endpoints further require Owner or Admin role).

Pick read for any third-party tool you do not fully trust (analytics dashboards, BI tools, ETL jobs that only need to copy data out). Pick read_write for your own application code.

Rotate a key

Click Rotate next to any key. A new plaintext bearer and signing secret are shown EXACTLY ONCE. The old values stop working immediately. There is no grace period; rotate during a maintenance window if you have many integrations to update.

Use rotation when:

• A team member with key access leaves.
• A key is accidentally committed to a public repo.
• Quarterly rotation as part of your security policy.

Revoke a key

Click Revoke. The key stops working immediately. Cannot be undone. If you need access back, create a new key.

Audit trail

Every key creation, rotation, and revocation is logged in the audit log at /dashboard/settings/audit-log. The audit row includes the team member who did it and the key's prefix (not the plaintext).

Where keys are visible

The list at /dashboard/settings/api-keys and GET /api/api-keys shows each key as:

• id
• name
• keyPrefix (first 12 chars of the bearer; safe to log)
• scopes (array of "read" / "read_write")
• lastUsedAt (timestamp, null if the key has never authenticated)
• expiresAt (null if non-expiring)
• revokedAt (null if active)
• createdAt

The plaintext bearer is never recoverable after creation. We also do not return the IP a key was last used from on the API or dashboard list; IPs land in the audit log instead, where they're scoped to JWT Owner dashboard callers only and are stripped from API-key callers (see Reference).

Signing secret

The signing secret is used for HMAC-SHA256 signatures on S2S endpoints. Separate from the bearer because:

• The bearer authenticates "who is making this request".
• The signing secret authenticates "the body of this request was not tampered with in transit".

Some integrations need only the bearer (most CRUD endpoints). S2S tracking requires both.

See S2S tracking for the signature format.

Webhook signing secret

Webhook outbound endpoints (the ones Rekomi POSTs events to) have their own signing secrets, separate from the API key signing secrets above. When you create a webhook endpoint at /dashboard/settings/webhooks, you get a one-time-shown signing secret for verifying inbound payloads on your server.

The two secrets do not interchange. Use the right one for the right direction.

Best practices

• Store keys in a secrets manager (1Password, AWS Secrets Manager, HashiCorp Vault). Never commit to source control. We run gitleaks scans on our own repos; you should too.
• Use separate keys per environment (one for prod, one for staging). Use scopes (one read for monitoring, one read_write for app code).
• Rotate quarterly even without incidents.
• Set X-Rekomi-Source header (any value) on your requests so they are easier to identify in our logs when you need support.

What if you lose a key

Rotate from the dashboard. If you cannot access the dashboard (account compromise), chat with us from any rekomi.com page (the messenger is in the bottom right, no login required) and we can revoke server-side. For coordinated disclosure of vulnerabilities, see security.txt.