Authentication

Documentation Index

Fetch the complete documentation index at: https://developers.beta.dealroom.co/llms.txt

Use this file to discover all available pages before exploring further.

• Programmatic (M2M) keys — for server-side integrations using the OAuth2 client credentials grant. Each key has a client_id and client_secret.
• Browser app (application) keys — for single-page apps (SPAs) using Authorization Code + PKCE. No client_secret; read-only permissions only.

​

Creating an API key

​

From the Dealroom dashboard

1. Choose the key type: Programmatic for server-side, Browser app for browser SPAs.
2. Enter a descriptive name (e.g. Production — Data Pipeline).
3. Click + Create key.
4. For Programmatic (M2M) keys: copy the client_id and client_secret immediately — the secret is shown only once. For application keys: copy the client_id — there is no secret in the SPA flow.

​

Quick start

import { ClientCredentials } from "simple-oauth2";
import axios from "axios";

const CLIENT_ID = process.env.DEALROOM_CLIENT_ID;
const CLIENT_SECRET = process.env.DEALROOM_CLIENT_SECRET;

// Set up OAuth2 client credentials
const oauth = new ClientCredentials({
  client: { id: CLIENT_ID, secret: CLIENT_SECRET },
  auth: {
    tokenHost: "https://accounts.beta.dealroom.co",
    tokenPath: "/oauth/token",
  },
});

// Create an axios instance with required headers
const dealroom = axios.create({
  baseURL: "https://api-next.beta.dealroom.co/api",
  headers: {
    "X-Client-Id": CLIENT_ID,
  },
});

// Auto-refresh token before every request
let token = await oauth.getToken({ audience: "https://api-next.beta.dealroom.co" });

dealroom.interceptors.request.use(async (config) => {
  if (token.expired()) {
    token = await oauth.getToken({ audience: "https://api-next.beta.dealroom.co" });
  }
  config.headers.Authorization = `Bearer ${token.token.access_token}`;
  return config;
});

// Make requests — token handling is automatic
const { data } = await dealroom.get("/entities", {
  params: { limit: 10, sort: "-launch_date" },
});
console.log(data);

npm install simple-oauth2 axios

pip install authlib requests

​

Obtaining a Bearer token

curl -X POST https://accounts.beta.dealroom.co/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api-next.beta.dealroom.co",
    "grant_type": "client_credentials"
  }'

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400
}

​

Making authenticated requests

curl "https://api-next.beta.dealroom.co/api/entities?limit=10&sort=-launch_date" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"

​

Why two headers?

• Authorization — authenticates the request via JWT.
• 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

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "X-Client-Id header is required for API key requests"
  }
}

​

Permissions

​

Usage dashboard

• Total requests — aggregated request count over time
• Endpoint breakdown — which endpoints are being called and how often
• Last used — when each key was last active

​

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.