Docs/Api Reference/Authentication

API Authentication

Anvil uses API keys for all programmatic access. This page covers how to issue, rotate, and revoke keys safely.

API Keys

Every API key is a Bearer token scoped to a single tenant. Keys look like this:

anv_live_sk_49kPz9... (production)
anv_test_sk_49kPz9... (sandbox)

Treat keys as passwords. Never commit them to Git, never paste them into client-side JavaScript, and never share them over unencrypted channels.

Creating a Key

  • Navigate to **Settings > API Keys** in the dashboard.
  • Click **Create Key**.
  • Give the key a human-readable label (e.g. "staging-cron" or "zapier-webhook").
  • Choose a scope (see below).
  • Set an optional expiry — we strongly recommend expiring all non-prod keys after 90 days.
  • Click **Generate**. The full key is shown exactly once. Copy it into your secrets manager immediately.

    • Using the Key

    Pass the key in the Authorization header on every request:

    curl https://api.anvilhk.com/v1/leads \
  -H "Authorization: Bearer anv_live_sk_49kPz9..." \
  -H "Content-Type: application/json"

    Responses include the authenticated tenant on every call via the X-Anvil-Tenant response header, so you can sanity-check you hit the right account.

    Scopes

    Keys can be narrowly scoped to reduce blast radius:

  • read:leads: — list and fetch leads only.
  • write:leads: — create, update, and tag leads.
  • read:conversations: — fetch AI chat sessions and messages.
  • write:conversations: — send messages and take over bot sessions.
  • admin: — full access including billing and team (Enterprise plans only).

    • Always grant the narrowest scope that covers your use case. A Zapier integration that only creates leads should not carry an admin key.

    Rotating Keys

    We recommend rotating production keys every 90 days. To rotate:

  • Create a new key with the same scope.
  • Deploy the new key to all consumers.
  • Verify traffic is flowing on the new key via **Settings > API Keys > Usage**.
  • Revoke the old key.

    • Anvil supports overlapping keys so you can rotate with zero downtime.

    Revoking Keys

    Navigate to **Settings > API Keys**, click the key, and choose **Revoke**. Revocation takes effect within five seconds globally. Any request made with a revoked key returns HTTP 401 with error.code = "KEY_REVOKED".

    If a key is accidentally leaked (e.g. committed to a public repo), revoke it immediately. We automatically scan GitHub for leaked keys via GitHub's secret-scanning partner program and will revoke on detection.

    OAuth 2.0 for Partner Apps

    If you are building an app that acts on behalf of multiple Anvil customers, use our OAuth 2.0 flow instead of static API keys. Register your app at **Developer Portal > OAuth Apps**, then redirect users to:

    https://api.anvilhk.com/v1/oauth/authorize?client_id=...&scope=read:leads&redirect_uri=...

    The authorization-code grant returns a refresh token valid for 30 days. See the [OAuth integration guide](/docs/integrations/custom) for the full flow.

    ← Back to Docs