Authentication

Authenticate API requests using bearer token API keys created in your DealSurface dashboard.

API keys

API keys are managed in your DealSurface dashboard under Settings → API Keys. Each key is scoped to your team and prefixed with ds_live_.

The raw key is shown only once at creation time. DealSurface stores a SHA-256 hash; if you lose the key, you must create a new one.

Pass your API key in the Authorization header with the Bearer scheme:

curl https://dealsurface.com/api/v1/products \
  -H "Authorization: Bearer ds_live_abc123..."

Keep keys secret

Never embed API keys in client-side code or commit them to version control. Use environment variables or a secrets manager.

Each API key has one or more scopes that control what it can access:

Scope	Grants access to
`read`	All GET endpoints: products, prospects, excerpts. Required for POST endpoints as well.
`outreach`	POST /dealmap/generate, PATCH /dealmap/*, and POST /outreach. Must be combined with `read`.

If you only need to read data, create a key with just the read scope. Grant outreach only to keys that need to generate DealMaps or outreach.

Authentication failures return the following status codes:

Status	Meaning
401	Missing or invalid API key, or key has expired.
403	Valid key but insufficient scopes, or API access disabled for your team.

Example: 401 Unauthorized

{
  "error": "Invalid or expired API key"
}