# Developer Quick Start — API Keys & Authentication

_Developers_

Every integration starts with an API key. CRMown has two kinds: Public API keys for the partner API at /api/v1 (safe to give a third-party tool like Clay), and Internal keys that act like a signed-in user across the whole app. Send the key as a Bearer token.

## Steps
1. In CRMown go to Settings → Integrations and scroll to the Developer section → API Keys.
2. Click create, name the key, and choose the type: "Public API" (limited to contacts, companies, leads and notes — recommended for third parties) or "Internal" (full access, like a signed-in user).
3. For a Public API key, tick only the permissions the tool needs: Look up contacts (contacts:read), Create & update contacts (contacts:write), Create & update companies (companies:write), Create leads (leads:write), Add notes (notes:write).
4. Confirm the security check (creating a key asks you to verify it is you), then copy the key. It is shown only once — store it in your tool's secret settings.
5. Call the API with the header Authorization: Bearer <your key>. Base URL: https://app.crmown.io/api.

## Tips
- Keys start with ck_live_. CRMown stores only a hash, so a lost key can't be recovered — create a new one and revoke the old.
- A key acts as the person who created it. If that user is deactivated, or resets/changes their password, or uses "Log out all devices", their keys stop working immediately — create integration keys from a long-lived admin account.
- Use the right type for the right door: a Public API key used on an internal route — or an Internal key used on /api/v1 — is refused with 403 wrong_api_surface.
- Rate limits — Public API: 600 requests per minute per key (responses carry x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset; a 429 includes retry-after). Internal keys follow your plan: Starter 60/min and 10,000/day, Pro 120/min and 50,000/day, Max 300/min and 200,000/day.
- Revoke a key any time from the same list; revoking takes effect on the next request.

### Test your key
```
curl -H "Authorization: Bearer ck_live_YOUR_KEY" \
  "https://app.crmown.io/api/v1/contacts/search?email=someone@example.com"
```

## Troubleshooting
- **401 unauthorized** — The key is missing, mistyped, revoked, expired, or its owner was deactivated or changed their password. Fix: Check the Authorization: Bearer header, then create a fresh key from an active admin account.
- **403 wrong_api_surface** — A Public API key was used on an internal route, or an Internal key on /api/v1. Fix: Use a Public API key for /api/v1 endpoints; use an Internal key for everything else.
- **403 insufficient_scope** — The key does not have the permission that endpoint needs (the response names it in "required"). Fix: Create a new Public API key with that permission ticked.