Authentication - Recover

Partner API Key

All Partner API requests require a Partner API Key passed in the request header.

X-Partner-Key: pk_live_abc123def456...

Or as a Bearer token:

Authorization: Bearer pk_live_abc123def456...

Getting a Partner API Key

Partner API keys are provisioned during onboarding. Contact your Recover account manager or email adyan@cove.dev. Each key is scoped to your partner account and grants access to all sub-accounts under it.

Key Format

Keys follow the format pk_live_ followed by 32 characters. Keep your key secret — it grants full access to create and manage accounts, import leads, and generate embed tokens.

Never expose your Partner API key in client-side code. All API calls should be made from your backend server.

Key Rotation

To rotate a key, contact your account manager. The old key will remain valid for 24 hours after the new key is issued.

Rate Limits

Endpoint	Limit
Account creation	100 / hour
Lead import (single)	1,000 / minute
Lead import (bulk)	50 / minute
Embed token generation	500 / hour
Conversation reads	5,000 / minute
Message sends	100 / minute per account
All other endpoints	1,000 / minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1771200000

When rate limited, the API returns 429 Too Many Requests with a Retry-After header.

Error Format

All errors follow a consistent format:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing Partner API key",
    "status": 401
  }
}

Error Codes

Code	Status	Description
`unauthorized`	401	Invalid or missing Partner API key
`forbidden`	403	Key does not have access to this resource
`not_found`	404	Account, lead, or resource not found
`invalid_phone`	400	Phone number format is invalid
`duplicate_lead`	409	Lead with this external_id already exists
`account_deactivated`	403	Account has been deactivated
`token_expired`	401	Embed token has expired
`rate_limited`	429	Too many requests
`validation_error`	422	Request body failed validation
`internal_error`	500	Internal server error

​Partner API Key

​Getting a Partner API Key

​Key Format

​Key Rotation

​Rate Limits

​Error Format

​Error Codes

Partner API Key

Getting a Partner API Key

Key Format

Key Rotation

Rate Limits

Error Format

Error Codes