API Keys & Scopes

Key Types

Create a Key

In the Panda IDX dashboard, open the account menu and choose API Keys, then Create API Key. Give it a name you will recognize (Zapier, Zillow leads), pick when it expires and choose its access. The full key is shown only once: copy it into your integration's secrets right away. You need permission to manage integrations on the account.

Scopes

A restricted key has one level per area: No access, Read or Read & write. As scopes they are <area>:read and <area>:write, and write includes read. The area names are the same ones the MCP server uses, so one vocabulary covers the REST API and AI tools. More areas appear here as they get endpoints.

Full Access

Turn off Restrict access to give a key full access (scope *). It reaches every area, including areas added later. Areas that send email or publish your website are never included by full access: a key only gets them when you pick them. Prefer restricted keys for anything you hand to a third party.

Expiry and Revoking

A key never expires unless you choose 30 days, 90 days or 1 year when you create it. An expired key answers 401. Revoke a key from the API Keys list at any time; it stops working on its next request. To change a key's access, create a new key, move your integration to it and revoke the old one. An account can have up to 20 active keys.

Test Your Key

GET /v1/me returns the key's name, scopes and expiry and the account it belongs to. Any valid key can call it.

curl --request GET \
  --url "https://api.pandaidx.com/v1/me" \
  --header "Authorization: Bearer YOUR_API_KEY"

Errors

Errors are { error: { code, message, details? } }. 401 means the key is missing, invalid, revoked or expired. A key without the scope an endpoint needs gets 403 with code insufficient_scope; details.required names the missing scope and details.granted lists what the key has. The same answer carries WWW-Authenticate: Bearer error="insufficient_scope".

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the \"contacts:write\" scope. Create a key with that access in Panda › Account › API Keys.",
    "details": {
      "required": "contacts:write",
      "granted": "contacts:read",
      "docs": "https://pandaidx.com/docs/api/authentication"
    }
  }
}

Keep Keys Safe

• Never put a secret key in a website, a browser extension or a mobile app. Use the public website key there.
• Give each integration its own key, so you can revoke one without breaking the others.
• Give each key only the areas it needs, and an expiry when the integration is temporary.
• If a key leaks, revoke it right away and create a new one.