Authentication

The GetRaze API uses API keys to authenticate requests.

Getting Your API Key

1. Log in to your GetRaze dashboard
2. Navigate to Settings > API Keys
3. Click Create API Key
4. Configure permissions and rate limits
5. 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)
tags:write	Create tags (MCP: contacts_add_tags with create_missing)
conversations:write	Send messages, add notes and take control of conversations (MCP; 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).

Key Rotation

For security, we recommend rotating your API keys periodically:

1. Create a new API key with the same permissions
2. Update your applications to use the new key
3. 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