Skip to main content

API Keys

Partner API keys authenticate your backend with the Loyva API. Keys are provisioned for you by your Loyva point of contact and are scoped to specific permissions.

Key format​

lk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
  • Prefix: lk_
  • Body: 40 hexadecimal characters
  • Total: 43 characters

Getting a key​

During onboarding, Loyva will provision an API key for your integration and share:

  • The raw lk_... key (shown once, at provisioning time — store it immediately in your secrets manager)
  • The scopes granted on the key (see Scopes)
  • A rate_limit_rpm ceiling
danger

The raw key is only shown once. Loyva stores it as a SHA-256 hash and cannot recover it later. If you lose the key, ask your Loyva point of contact to rotate it — a rotation issues a new raw key and invalidates the previous one atomically.

Using a key​

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

curl https://api.stg.loyva.net/api/v2/partner/envelopes \
  -H "X-API-Key: lk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"

The organization is derived from the key — no additional org header is required.

Key lifecycle​

ActionWhoNotes
CreateLoyvaA raw key is returned once; the hash is stored server-side
RotateLoyvaIssues a new raw key and invalidates the previous one atomically
Update scopes / rate limitLoyvaNon-disruptive — the same key keeps working
Manage webhook endpointsYouSelf-serve, and independent of keys — see Managing endpoints
DeactivateLoyvaKey is rejected on the next request

Reach out to your Loyva point of contact to request key creation, rotation, scope changes, or deactivation. You can verify a key is active by making a GET /api/v2/partner/envelopes request — a 401 means the key is invalid or deactivated.

Rate limits​

Every partner key has a rate_limit_rpm ceiling (requests per minute). The default is 100 RPM. When exceeded, the API returns:

HTTP 429 Too Many Requests
Retry-After: 60
{ "error": "Rate limit exceeded" }

Your key's current RPM ceiling is included in the provisioning response. Contact your Loyva point of contact to raise it.

Multi-tenant fan-out​

If you need per-tenant (e.g. per-dealer) isolation on outbound calls, provision one Loyva API key per tenant:

  • Each key has its own rate_limit_rpm ceiling, preventing one tenant from consuming another's quota
  • Each key has its own scopes, so a tenant integration grants only what it needs

Ask your Loyva point of contact to provision the set in one batch — high-volume or automated onboarding is supported, arranged per integration.

Webhooks are not routed per key

Webhook endpoints are org-wide. Registering an endpoint does not tie it to an API key, and events are not attributed to the key that caused them — most events have no key at all (console actions, scheduled jobs, inbound provider webhooks).

Route by tenant inside your receiver, using customer_id or your own external_id:

POST https://your-app.com/hooks/loyva   →   switch on data.customer_id → dealer 123 / 456

Use external_id on envelopes to correlate Loyva records with your own tenant IDs.

Keys and webhooks are separate​

An API key authenticates your outbound calls to Loyva. A webhook endpoint receives Loyva's inbound calls to you. They are independent objects:

  • Endpoints are org-wide and are not attached to a key
  • Creating, rotating, or revoking a key has no effect on webhook delivery
  • Each endpoint has its own signing secret, unrelated to any API key

Manage endpoints under Webhooks.

Webhook deliveries​

Every attempted delivery is recorded — status, response code and body, attempt count, duration, and next retry time — and is readable self-serve via GET /api/v2/webhooks/endpoints/:endpoint_id/deliveries or in the console. Any delivery can be replayed. See Managing endpoints.

Security best practices​

  1. Never commit keys to source control — use environment variables or a secrets manager.
  2. Never expose keys in frontend code — keys are for server-to-server use only. Mint short-lived embed tokens for the browser instead.
  3. Use separate keys per environment — dev, staging, production.
  4. Scope keys minimally — only request the scopes your integration actually needs.
  5. Rotate on a schedule — rotations are atomic; plan for a brief window where both old and new secrets are deployed during the cut-over.
  6. Monitor last_used_at — if a key hasn't been used, it may be leaked or unnecessary; ask for it to be deactivated.