Authentication
The GetRaze API uses API keys to authenticate requests.
Getting Your API Key
- Log in to your GetRaze dashboard
- Navigate to Settings > API Keys
- Click Create API Key
- Configure permissions and rate limits
- Copy your API key (it will only be shown once)
WARNING
Keep your API key secure. Never share it in public repositories or client-side code.
Using Your API Key
Include your API key in every request using one of these methods:
Header (Recommended)
curl --request GET \
--url "https://app.getraze.com/external/v1/contacts" \
--header "X-API-Key: lr_live_xxxxxxxxxxxxx"Bearer Token
curl --request GET \
--url "https://app.getraze.com/external/v1/contacts" \
--header "Authorization: Bearer lr_live_xxxxxxxxxxxxx"Query Parameter
curl --request GET \
--url "https://app.getraze.com/external/v1/contacts?api_key=lr_live_xxxxxxxxxxxxx"TIP
We recommend using the X-API-Key header for security. Query parameters may be logged by servers.
API Key Permissions
When creating an API key, you can configure granular permissions:
| Permission | Allows |
|---|---|
contacts:read | List and retrieve contacts |
contacts:write | Create and update contacts |
contacts:delete | Delete contacts |
opportunities:read | List and retrieve opportunities |
opportunities:write | Create and update opportunities |
opportunities:delete | Delete opportunities |
campaigns:read | List campaigns |
campaigns:write | Add contacts to campaigns |
instagram_agents:read | List Instagram agents |
instagram_agents:write | Add profiles to Instagram agents |
pipelines:read, sectors:read, tags:read, discard_reasons:read, products:read, users:read | Read reference lists |
conversations:read | List conversations and read messages |
reports:read | Read aggregated reports (funnel, sales summary, sellers, SLA) |
tasks:read | List and retrieve tasks, their comments, task pipelines and labels |
tasks:write | Create, update, complete and comment on tasks |
tasks:delete | Delete tasks |
playbooks:read | List playbooks, their steps and runs |
playbooks:run | Start, cancel and reschedule playbook runs |
tags:write | Create tags (MCP: contacts_add_tags with create_missing) |
conversations:write | Transfer conversations (assign user and sector). Via MCP, also send messages, add notes and take control. Admin only |
knowledge:read | Search an AI employee's knowledge base (MCP) |
agents:read | List AI employees (MCP) |
agents:run | Chat with an AI employee in a sandbox (MCP; admin only) |
agent_tools:execute | Run AI employee actions on real contacts (MCP; admin only) |
Wildcard permissions are supported (e.g., contacts:* grants all contact permissions).
Tasks and playbooks follow the key's creator
Task and playbook endpoints show what the user who created the key sees in the app: admins see everything in the account, other users see their own work. Writes done with the key are authored by that user.
Key Rotation
For security, we recommend rotating your API keys periodically:
- Create a new API key with the same permissions
- Update your applications to use the new key
- Revoke the old API key
Authentication Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | MISSING_API_KEY | No API key provided |
| 401 | INVALID_API_KEY | API key is invalid or revoked |
| 403 | INSUFFICIENT_PERMISSIONS | API key lacks required permission |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests |