Authentication

Authenticate API requests using secret API keys. All requests to the /api/v1 endpoints require a valid API key.

How It Works

Reechdesk uses API keys to authenticate programmatic access. Each key is tied to a company and carries a set of permission scopes that control what resources it can access.

1. Create a Key

Generate a key from your dashboard settings with the permissions you need.

2. Include It

Add the X-API-Key header to every request.

3. Make Requests

Access all endpoints your key's permissions allow.

Creating API Keys

Navigate to Settings → API Keys in your dashboard.
Click Create Key.
Choose a key type: TEST for development or LIVE for production.
Select the permission scopes this key needs.
Set a rate limit (default: 1,000 requests/hour).
Copy the key immediately — it won't be shown again.

Keep your keys secure

API keys grant access to your account. Never expose them in client-side code, public repositories, or browser networks. Use them only in server-to-server communication.

Key Format

API keys follow a standardized format with a prefix that identifies the key type:

Type	Prefix	Example	Use Case
TEST	rd_test_	rd_test_a1b2c3d4e5f6...	Development, staging, testing
LIVE	rd_live_	rd_live_a1b2c3d4e5f6...	Production environments

Using API Keys

Include your API key in the X-API-Key header with every request to the /api/v1 endpoints.

curl -X GET https://your-domain.com/api/v1/tickets \
  -H "X-API-Key: rd_live_your_api_key_here"

Permission Scopes

Each API key carries a set of permission scopes that control which resources it can access. When creating a key, select only the scopes your integration needs.

Scope	Description
tickets:read	View tickets, comments, and activities
tickets:write	Create, update, and escalate tickets
tickets:delete	Delete tickets
kb:read	View knowledge base articles and categories
kb:write	Create and update articles and categories
kb:delete	Delete articles and categories
chat:read	View chat sessions and messages
chat:write	Send messages and manage sessions
users:read	View user profiles and team members
users:write	Create and update users
entities:read	View entities and subsidiaries
entities:write	Create and update entities
reports:read	View reports and analytics
settings:read	View company settings
settings:write	Update company settings
api-keys:read	View API keys
api-keys:write	Create, update, and delete API keys
billing:read	View billing and subscription info
billing:write	Manage billing and subscriptions

Rate Limiting

Each API key has a configurable rate limit (default: 1,000 requests/hour). When the limit is exceeded, the API returns a 429 Too Many Requests response.

Every API response includes rate limit headers so you can monitor your usage:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per hour
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Seconds until the rate limit window resets

Response429

json

{
  "error": "Rate limit exceeded. Try again in 847 seconds."
}

Error Responses

When authentication fails, the API returns a descriptive error with the appropriate HTTP status code:

Status	Meaning	Common Causes
401	Unauthorized	Missing API key, invalid key, or expired key
403	Forbidden	Valid key but missing required permission scope, or account inactive/suspended
429	Too Many Requests	Rate limit exceeded. Check `X-RateLimit-Reset` header

Example Error Responses

Missing API Key

bash

curl -X GET https://your-domain.com/api/v1/tickets

401 Unauthorized401

json

{
  "error": "X-API-Key header required. Get your key at https://app.reechdesk.com/settings/api-keys"
}

Insufficient Permissions

bash

curl -X DELETE https://your-domain.com/api/v1/tickets/tkt_abc123 \
  -H "X-API-Key: rd_live_your_key"

403 Forbidden403

json

{
  "error": "Missing required permission: tickets:delete"
}

Invalid Key

bash

curl -X GET https://your-domain.com/api/v1/tickets \
  -H "X-API-Key: rd_live_invalid_key_here"

401 Unauthorized401

json

{
  "error": "Invalid API key"
}

Security Best Practices

•Never expose keys client-side. Use API keys only in server-to-server communication. Do not include them in JavaScript, mobile apps, or browser requests.
•Use test keys for development. Create separate TEST keys for staging and development environments.
•Apply least-privilege permissions. Only grant the permission scopes your integration actually needs.
•Rotate keys regularly. Delete old keys and create new ones periodically. Deactivate keys you're no longer using.
•Store keys securely. Use environment variables or a secrets manager. Never commit keys to source control.
•Monitor usage. Check the X-RateLimit-Remaining header and review key usage in the dashboard.