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
• Your configured webhook URL, if you've supplied one

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

Action	Who	Notes
Create	Loyva	A raw key is returned once; the hash is stored server-side
Rotate	Loyva	Issues a new raw key and invalidates the previous one atomically
Update scopes / rate limit	Loyva	Non-disruptive — the same key keeps working
Update webhook URL / secret	You	Self-serve via PATCH /api/v2/partner/webhook
Deactivate	Loyva	Key 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) event routing, provision one Loyva API key per tenant:

• Each key routes webhook deliveries to its own webhook_url
• Each key has its own rate_limit_rpm ceiling, preventing one tenant from consuming another's quota
• Keys can be provisioned programmatically via the Platform Provisioning API (POST /api/v2/platform/orgs/:org_id/partner-keys) using the X-Platform-Secret header — suitable for automated onboarding flows

Tenant A → lk_aaa... → webhook: https://your-app.com/hooks/dealer/123
Tenant B → lk_bbb... → webhook: https://your-app.com/hooks/dealer/456

Use external_id on envelopes to correlate Loyva records with your own tenant IDs, and maintain a mapping of partner_key_id → tenant on your side.

Webhook deliveries

If you've configured a webhook URL on your key, every attempted delivery is recorded in Loyva's delivery log. Loyva can share a paginated log for your key on request (delivery ID, status code, attempt count, next retry time).

To update your webhook URL or rotate your signing secret at any time, use PATCH /api/v2/partner/webhook — no need to contact Loyva. See Webhooks for details.

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.