veil

Use a developer API key

Give a server integration a shared allowance without granting authority over a Veil card.

Public reads and message verification still work without an API key. A developer key gives your server a separate allowance, shared by every key owned by the same person or organisation. Open /developers from your account to manage them.

Create and store the key#

An active device signs the creation request. A person manages their own keys; an organisation needs an accepted owner. Choose a label, read and/or verify scope, and an expiry of 1 to 365 days. The default is 90 days. Each owner can have 20 unexpired, unrevoked keys, including suspended ones.

The creation response shows secret once. Veil stores only its SHA-256 hash. Put the value in your server’s secret configuration and send it in an Authorization Bearer header. Never put it in a URL, repository, public JavaScript bundle or shared screenshot. Your Veil device’s private signing key stays in its device.

cURL
curl -fsS \
  -H "Authorization: Bearer $VEIL_API_KEY" \
  "https://veil.rip/v1/lookup?key=73ad6159583a43f8ad230a215b758db680efcd3ce32ab8e83c622eeca883e68a"

Understand the allowance#

The default owner bucket holds 600 requests and refills at 600 per minute. Message verification uses that bucket and a second bucket holding 120 verifications, refilling at 120 per minute. These are continuous token buckets, so a short burst can use the available balance. Counters live in PostgreSQL and survive restarts. Creating or rotating a key does not reset them.

Authenticated reads use the owner’s allowance instead of the anonymous 300-per-minute IP budget. A separate outer limit of 3000 API-key requests per minute per IP and bounded authentication concurrency still apply. Public requests without a key keep their current limits. API keys do not raise signed-write, card-creation, pairing or account-linking limits.

Staff may set an additional per-key cap, a custom owner allowance or a daily owner cap. A key’s allowance never adds to the owner’s total. Daily caps reset at midnight UTC. Admitted API requests count even when their endpoint later returns an error. Requests rejected by an API quota are counted separately.

Read the response headers#

X-RateLimit-Limit and X-RateLimit-Remaining describe the effective bucket for this request. X-RateLimit-Reset is Unix seconds when the reported bucket can be full again without further requests. X-RateLimit-Resource identifies requests, verification, key or daily. A 429 rate_limited response includes Retry-After in seconds, calculated for the next admissible request.

GET /v1/rate-limit returns the current key and owner quotas without spending the primary allowance. It still requires a valid key and counts against the outer IP guard. Signed management reads show daily usage and the latest 31 days of history. API-key responses use no-store.

Rotate, revoke and handle suspension#

Create a replacement, update your integration, then revoke the old key. Revocation is permanent. Staff may suspend and restore individual keys, revoke them permanently or suspend all API access for an owner. Creating another key cannot bypass an owner suspension. Existing key expiry and card suspension or erasure remain effective.

Invalid, expired or revoked keys return 401 invalid_api_key. Scope violations return 403 api_key_scope. A suspended key returns 403 api_key_suspended; blocked owner access returns 403 developer_suspended. These requests never silently fall back to anonymous access.

Keep browser integrations public#

Secret bearer keys are for server or local clients. Authorization is not opened by public CORS. Browser integrations can still call public endpoints anonymously. Key management uses your device signature, not the bearer key. API keys do not grant staff roles or authority to publish identity versions.

Inspect private activity#

Creation, owner revocation, staff actions and custom limits keep a private receipt with the exact signed management request. Owners and authorised staff can inspect it. Secrets never appear in the receipt or public identity log. Usage records contain aggregate counts rather than messages, lookup queries or IP addresses.

Device signing keys and integration API keys have separate lifetimes. Revoking a device does not revoke API keys it issued. After a device compromise, inspect the private receipts and revoke the affected integration keys too.

Read this entry as JSON