Authentication and key management

Valara uses API keys for external integrations and session cookies for the in-product developer settings UI. This page covers the API key lifecycle: minting, scoping, rotating, and revoking.

Key formats

Format	Environment	Notes
sk_live_*	Production	Touches real data, fires real side effects
sk_test_*	Sandbox	Isolated sandbox tour pool, shunted side effects

The prefix is the only signal an observer needs to recognize a leaked key. Treat both prefixes as high-value secrets.

How to authenticate API requests

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

GET /api/v1/listings HTTP/1.1
Host: valara.cloud
X-API-Key: sk_live_your_key_here

An Authorization: Bearer header is also accepted as an alias, but X-API-Key is preferred and matches the OpenAPI spec annotations.

Both production hosts accept the same keys:

https://valara.cloud/api/v1/
https://dash.jacoballenmedia.com/api/v1/

Creating a key

1. Sign in at https://valara.cloud/login.

2. Navigate to Developer > API Keys.

3. Click Create new key.

4. Enter a descriptive name (required) - use the integration name, e.g. "Production CRM sync" or "Staging test suite".

5. Select scopes (the default is listings:read only):

   Scope	Permits
   listings:read	GET /api/v1/listings, GET /api/v1/listings/{n}, GET /api/v1/listings/{n}/orders
   listings:write	POST /api/v1/listings, PATCH /api/v1/listings/{n}/status, POST /api/v1/listings/{n}/cancel, PATCH /api/v1/listings/{n}/sections/*
   media:write	POST /api/v1/media/upload
   scheduling:read	GET /api/v1/scheduling/availability
   users:read	GET /api/v1/users
   webhooks:read	GET /api/v1/webhooks/events (catalog)

6. Toggle Sandbox if you want a sk_test_* key.

7. Click Create.

The full plaintext key is displayed once in a reveal-once portal. You must check "I have copied and saved this key securely" before dismissing. We do not retain the plaintext - if you lose the key, you must rotate it to get a new one.

Rotating a key

Use case: scheduled rotation, suspected compromise, employee turnover.

1. Navigate to Developer > API Keys.
2. Find the key, click Rotate.
3. Confirm in the modal. The new plaintext is shown once.
4. The old key remains valid for 30 days (the rotation grace window) so you can deploy the new key without an outage.
5. After 30 days the old key is automatically invalidated.

Revoking a key

Use case: confirmed leak, integration retired, key no longer needed.

1. Navigate to Developer > API Keys.
2. Find the key, click Revoke.
3. Confirm in the destructive-action modal.
4. The key is invalidated within ~60 seconds (subject to the in-process cache TTL on our side).
5. The audit trail at /manage/developer/audit records the revoke event with your user ID and timestamp.

Revocation is a soft-delete - the audit trail is retained indefinitely.

Scoping best practices

• One key per integration. Easier to revoke when an integration is decommissioned without affecting others.
• Minimum scopes. A read-only sync only needs listings:read. Narrower scopes limit blast radius if the key leaks.
• Rotate quarterly. Build the rotation into your deploy pipeline.
• Never commit plaintext to source control. Use environment variables or a dedicated secrets manager.

Monitoring key usage

/manage/developer/analytics shows per-key request volume, error rates, and p95 latency. An unexpected spike in error rate often indicates a misconfigured key or an in-progress compromise.

/manage/developer/access-log shows every tour that was accessed via each key with timestamps and response codes - useful for SOC2 or GDPR-flavored access audits.

Test console

The in-app test console at /manage/developer/console lets you fire real API requests from the browser without exposing the plaintext key to your browser's DevTools. You select a key by name; the server looks up the plaintext in an in-process cache and proxies the request through the full middleware stack (rate limiting, agency scoping, idempotency all execute).

This means test console runs count against your rate limit budget. The console has its own separate limit of 60 runs per minute per agency.

Error responses

All authentication errors use a consistent JSON envelope:

{
  "error": {
    "code": "authentication_failed",
    "message": "API key is invalid or revoked.",
    "request_id": "req_01HXREQUESTID"
  }
}

HTTP status	code value	Meaning
401	authentication_failed	Missing, malformed, or revoked key
403	insufficient_scope	Key exists but lacks the required scope
429	rate_limit_exceeded	See Rate limits