Authentication

All API requests (except webhooks) require authentication. 500 Leads supports two methods:

1. JWT Tokens (Dashboard sessions)

When you log in through the dashboard, you receive a JWT access token and a refresh token. These are managed automatically by the frontend.

For programmatic use, you can obtain tokens via:

POST /api/auth/login

{
  "email": "[email protected]",
  "password": "your-password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "usr_...",
    "email": "[email protected]",
    "name": "Your Name"
  }
}

Include the token in subsequent requests:

curl https://leads.500rockets.io/api/leads \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

2. API Keys (Recommended for integrations)

API keys are the recommended way to authenticate external integrations, scripts, and third-party tools.

Generating a key

Go to Settings > API Keys in the dashboard and click Generate New Key. You will see the full key once. Copy it immediately and store it securely.

Keys look like: 5l_live_a1b2c3d4e5f6...

Using a key

Include the key in the X-API-Key header:

curl https://leads.500rockets.io/api/leads \
  -H "X-API-Key: 5l_live_a1b2c3d4e5f6..."

Or in the Authorization header:

curl https://leads.500rockets.io/api/leads \
  -H "Authorization: ApiKey 5l_live_a1b2c3d4e5f6..."

Scopes

Scope	Description
read	Can read leads, sources, pipelines, and stats. Cannot create, update, or delete.
full	Full read and write access. Can create leads, update statuses, manage tags, etc.

Key management

Endpoint	Description
GET /api/api-keys	List all keys (admin only)
POST /api/api-keys	Generate a new key
PATCH /api/api-keys/:id	Update label or active status
DELETE /api/api-keys/:id	Permanently delete a key

Security notes

• Keys are hashed with SHA-256 before storage. We never store the plaintext key.
• You can revoke a key at any time by toggling it to inactive or deleting it.
• Set an expiration date for keys used in temporary integrations.

Rate limiting

All API requests are rate-limited to 100 requests per minute per IP address. If you exceed this limit, you will receive a 429 Too Many Requests response.

Errors

All error responses follow this format:

{
  "error": "Human-readable error message"
}

Status	Meaning
400	Bad request (validation error)
401	Missing or invalid authentication
403	Insufficient permissions (e.g. read-only key trying to write)
404	Resource not found
429	Rate limit exceeded
500	Server error