The Dealroom API uses API keys backed by Auth0 Machine-to-Machine (M2M) credentials.
Every request requires a short-lived Bearer token obtained by exchanging your API key credentials.
Creating an API key
Create an API key via the Dealroom dashboard or the API. You need the create:api-keys permission.
curl -X POST https://api.dealroom.co/api/api-keys \
-H "Authorization: Bearer $USER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Production integration",
"permissions": ["read:entities", "read:investors"]
}'
{
"data": {
"id": 1,
"name": "Production integration",
"client_id": "abc123def456",
"client_secret": "secret_shown_only_once",
"permissions": ["read:entities", "read:investors"],
"last_used_at": null,
"created_at": "2026-03-18T12:00:00.000Z"
}
}
Store client_id and client_secret securely. The secret is shown only once and cannot
be retrieved later. If lost, revoke the key and create a new one.
Obtaining a Bearer token
Exchange your credentials for an access token at the Auth0 token endpoint:
curl -X POST https://$AUTH0_DOMAIN/oauth/token \
-H "Content-Type: application/json" \
-d '{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"audience": "https://api.dealroom.co",
"grant_type": "client_credentials"
}'
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400
}
expires_in seconds (typically 24h). Cache and reuse them. Requesting
a new token per API call is unnecessary and adds latency.
Making authenticated requests
Every request must include three headers:
| Header | Description | Example |
|---|
Authorization | Bearer token from the token endpoint | Bearer eyJhbGciOiJSUzI1NiIs... |
User-Agent | Identifies your application | MyApp/1.0 (contact@example.com) |
X-Client-Id | The client_id issued when the API key was created | abc123def456 |
curl "https://api.dealroom.co/api/entities?limit=10&sort=-launch_year" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "User-Agent: MyApp/1.0 (you@example.com)" \
-H "X-Client-Id: YOUR_CLIENT_ID"
Authorization — authenticates the request via JWT.User-Agent — identifies your application in access logs for analytics and debugging,
without requiring JWT decoding on every log line.X-Client-Id — cross-checked against the token’s sub claim as an extra authenticity
guard. Must match the client_id used to obtain the token.
Error responses
Missing or invalid headers return 400 Bad Request:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "User-Agent header is required for API key requests"
}
}
Managing API keys
List your keys
curl https://api.dealroom.co/api/api-keys \
-H "Authorization: Bearer $USER_TOKEN"
Revoke a key
curl -X DELETE https://api.dealroom.co/api/api-keys/1 \
-H "Authorization: Bearer $USER_TOKEN"
Permissions
API keys support fine-grained scopes. You can only grant permissions that you already hold.
Common permissions:
| Permission | Description |
|---|
read:entities | Query companies, funds, people |
read:investors | Query investor profiles |
read:founders | Query founder profiles |
read:transactions | Query funding rounds |
read:valuations | Query company valuations |
Best practices
- Principle of least privilege — only grant permissions your integration needs.
- Rotate regularly — revoke and recreate API keys periodically.
- Never commit secrets — use environment variables or a secrets manager.
- Cache tokens — reuse the access token for its full lifetime before refreshing.
- Descriptive User-Agent — include your app name, version, and a contact email
(e.g.
MyApp/2.1 (api-team@company.com)).
