Authentication

The Dealroom API uses API keys for server-side integrations. Each key has a client_id and client_secret and uses the OAuth2 client credentials grant. The Quickstart covers creating a key, obtaining a Bearer token, and making your first request. Use this page when preparing a production integration or managing its credentials.

How credentials work

An API key and a Bearer token have different lifecycles:

The client_id and client_secret identify the integration. They remain valid until the key is revoked.
The Bearer token authenticates API requests. It is short-lived and is typically valid for 24 hours.

Token exchange

The Quickstart covers macOS, Linux, and Windows PowerShell. Command Prompt is documented here. Choose the language that matches your integration. The Node.js and Python examples read DEALROOM_CLIENT_ID and DEALROOM_CLIENT_SECRET from the environment. Save the Node.js example as an .mjs file so top-level await is enabled. The cURL and Command Prompt examples require curl and jq; the PowerShell example requires neither.

ACCESS_TOKEN=$(curl -fsS -X POST "https://accounts.dealroom.co/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api.beta.dealroom.app",
    "grant_type": "client_credentials"
  }' | jq -er '.access_token')

REM Request the token and save the response
curl -sS -X POST "https://accounts.dealroom.co/oauth/token" ^
  -H "Content-Type: application/json" ^
  -d "{\"client_id\": \"YOUR_CLIENT_ID\", \"client_secret\": \"YOUR_CLIENT_SECRET\", \"audience\": \"https://api.beta.dealroom.app\", \"grant_type\": \"client_credentials\"}" > token.json

REM Read the token out of it, then discard the file
for /f "delims=" %A in ('jq -er .access_token token.json') do set ACCESS_TOKEN=%A
del token.json

$body = @{
  client_id     = "YOUR_CLIENT_ID"
  client_secret = "YOUR_CLIENT_SECRET"
  audience      = "https://api.beta.dealroom.app"
  grant_type    = "client_credentials"
} | ConvertTo-Json

$token = Invoke-RestMethod -Method Post `
  -Uri "https://accounts.dealroom.co/oauth/token" `
  -ContentType "application/json" `
  -Body $body

$accessToken = $token.access_token
$token | Select-Object token_type, expires_in

const clientId = process.env.DEALROOM_CLIENT_ID;
const clientSecret = process.env.DEALROOM_CLIENT_SECRET;

if (!clientId || !clientSecret) {
  throw new Error("Set DEALROOM_CLIENT_ID and DEALROOM_CLIENT_SECRET");
}

const tokenResponse = await fetch("https://accounts.dealroom.co/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: clientId,
    client_secret: clientSecret,
    audience: "https://api.beta.dealroom.app",
    grant_type: "client_credentials",
  }),
});

if (!tokenResponse.ok) throw new Error(await tokenResponse.text());
const token = await tokenResponse.json();
const accessToken = token.access_token;
console.log({ token_type: token.token_type, expires_in: token.expires_in });

import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://accounts.dealroom.co/oauth/token",
    data=json.dumps(
        {
            "client_id": os.environ["DEALROOM_CLIENT_ID"],
            "client_secret": os.environ["DEALROOM_CLIENT_SECRET"],
            "audience": "https://api.beta.dealroom.app",
            "grant_type": "client_credentials",
        }
    ).encode(),
    headers={"Content-Type": "application/json"},
    method="POST",
)

with urlopen(request) as response:
    token = json.load(response)

access_token = token["access_token"]
print({"token_type": token["token_type"], "expires_in": token["expires_in"]})

The response includes the token and its lifetime:

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

The audience value (https://api.beta.dealroom.app) is an OAuth2 identifier, not necessarily a URL you call. It may match the API base URL (https://api.beta.dealroom.app) in one environment and differ in another. Use both values exactly as configured.

Token caching and refresh

A token is valid for 24 hours. Cache it and reuse it until shortly before it expires. Requesting a new token for every API call adds unnecessary latency and load, and a token that is never refreshed fails with 401 the next day. For anything that runs longer than a single session, store the token together with its expiry, refresh it shortly before expires_in elapses, and refresh it once more if a request still returns 401. A 401 that survives that one refresh means the key was revoked, not that the token expired. Stop retrying and check the key in the dashboard. The token lifetime is controlled by the identity provider and cannot be configured per API key. The helpers below do all of that with the standard library. Copy one into your project and call it instead of fetch or urlopen directly. Both read DEALROOM_CLIENT_ID and DEALROOM_CLIENT_SECRET from the environment.

const clientId = process.env.DEALROOM_CLIENT_ID;
const clientSecret = process.env.DEALROOM_CLIENT_SECRET;

if (!clientId || !clientSecret) {
  throw new Error("Set DEALROOM_CLIENT_ID and DEALROOM_CLIENT_SECRET");
}

let cached = { token: null, expiresAt: 0 };

async function getToken() {
  // Refresh a minute early so a request never carries a token that dies in flight.
  if (cached.token && Date.now() < cached.expiresAt - 60_000)
    return cached.token;

  const response = await fetch("https://accounts.dealroom.co/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      client_id: clientId,
      client_secret: clientSecret,
      audience: "https://api.beta.dealroom.app",
      grant_type: "client_credentials",
    }),
  });
  if (!response.ok) throw new Error(await response.text());

  const { access_token, expires_in } = await response.json();
  cached = { token: access_token, expiresAt: Date.now() + expires_in * 1000 };
  return cached.token;
}

export async function dealroomGet(path, params = {}) {
  const url = new URL(path, "https://api.beta.dealroom.app");
  for (const [key, value] of Object.entries(params)) {
    url.searchParams.set(key, String(value));
  }

  const send = async () =>
    fetch(url, {
      headers: {
        Authorization: `Bearer ${await getToken()}`,
        "X-Client-Id": clientId,
        "User-Agent": "my-app/1.0",
      },
    });

  let response = await send();
  if (response.status === 401) {
    // Expired early or revoked. Refresh once; a second 401 means the key is gone.
    cached = { token: null, expiresAt: 0 };
    response = await send();
  }
  if (!response.ok)
    throw new Error(`${response.status} ${await response.text()}`);
  return response.json();
}

// Usage:
// const companies = await dealroomGet("/data/companies", { limit: 10 });

import json
import os
import time
from urllib.error import HTTPError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

CLIENT_ID = os.environ["DEALROOM_CLIENT_ID"]
CLIENT_SECRET = os.environ["DEALROOM_CLIENT_SECRET"]

_cache = {"token": None, "expires_at": 0.0}


def get_token():
    # Refresh a minute early so a request never carries a token that dies in flight.
    if _cache["token"] and time.time() < _cache["expires_at"] - 60:
        return _cache["token"]

    request = Request(
        "https://accounts.dealroom.co/oauth/token",
        data=json.dumps(
            {
                "client_id": CLIENT_ID,
                "client_secret": CLIENT_SECRET,
                "audience": "https://api.beta.dealroom.app",
                "grant_type": "client_credentials",
            }
        ).encode(),
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    with urlopen(request) as response:
        body = json.load(response)

    _cache["token"] = body["access_token"]
    _cache["expires_at"] = time.time() + body["expires_in"]
    return _cache["token"]


def dealroom_get(path, params=None):
    url = "https://api.beta.dealroom.app" + path + ("?" + urlencode(params) if params else "")

    def send():
        request = Request(
            url,
            headers={
                "Authorization": f"Bearer {get_token()}",
                "X-Client-Id": CLIENT_ID,
                "User-Agent": "my-app/1.0",
            },
        )
        with urlopen(request) as response:
            return json.load(response)

    try:
        return send()
    except HTTPError as error:
        if error.code != 401:
            raise
        # Expired early or revoked. Refresh once; a second 401 means the key is gone.
        _cache["token"] = None
        _cache["expires_at"] = 0.0
        return send()


# Usage:
# companies = dealroom_get("/data/companies", {"limit": 10})

Required headers

Every request authenticated with an API key must include two headers:

Header	Description	Example
`Authorization`	Bearer token from the token endpoint	`Bearer eyJhbGciOiJSUzI1NiIs...`
`X-Client-Id`	The `client_id` issued when the API key was created	`abc123def456`

The Authorization header authenticates the request via JWT. X-Client-Id is cross-checked against the token’s sub claim and must match the client_id used to obtain the token.

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

curl -fsS "https://api.beta.dealroom.app/data/entities?limit=10&sort=-launch_date" ^
  -H "Authorization: Bearer %ACCESS_TOKEN%" ^
  -H "X-Client-Id: YOUR_CLIENT_ID" | jq .

$headers = @{
  Authorization = "Bearer $accessToken"
  "X-Client-Id" = "YOUR_CLIENT_ID"
}

Invoke-RestMethod -Uri "https://api.beta.dealroom.app/data/entities?limit=10&sort=-launch_date" -Headers $headers |
  ConvertTo-Json -Depth 10

const apiResponse = await fetch(
  "https://api.beta.dealroom.app/data/entities?limit=10&sort=-launch_date",
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "X-Client-Id": clientId,
    },
  },
);

if (!apiResponse.ok) throw new Error(await apiResponse.text());
console.log(JSON.stringify(await apiResponse.json(), null, 2));

request = Request(
    "https://api.beta.dealroom.app/data/entities?limit=10&sort=-launch_date",
    headers={
        "Authorization": f"Bearer {access_token}",
        "X-Client-Id": os.environ["DEALROOM_CLIENT_ID"],
        # urllib's default User-Agent is blocked at the edge
        "User-Agent": "my-app/1.0",
    },
)

with urlopen(request) as response:
    print(json.dumps(json.load(response), indent=2))

The PowerShell, Node.js, and Python request examples reuse the token variables created in the token exchange examples.

Cloudflare sits in front of the API and blocks some default HTTP-client User-Agent signatures, notably Python’s urllib, before the request reaches the API. Set an explicit User-Agent header in standard-library clients. See Errors for how to recognize the block.

Scopes and permissions

API keys support fine-grained scopes. You can only grant scopes held by your own account, and the API rejects requests outside the key’s granted scopes. Scopes cannot be edited after creation. Revoke the key and create another one to change them. Published data scopes include:

Scope	Access
`read:entities`	Companies, funds, and other entity data
`read:investors`	Investor profiles and portfolios
`read:founders`	Founder profiles
`read:people`	People profiles and entity team lists
`read:transactions`	Funding rounds
`read:valuations`	Company valuations
`read:news`	News articles
`read:jobs`	Job openings
`read:search`	Top-level entity search
`read:dimensions`	Filter dimensions and accepted values

Analytics scopes:

Scope	Access
`read:aggregate`	Aggregate analytics
`read:timeseries`	Timeseries analytics
`read:funding-analytics`	Funding-specific analytics

The analytics operations are not in the API Reference tab yet, so Analytics and aggregates is their reference for now. read:aggregate and read:timeseries cover endpoints being promoted into the frozen public API contract. The funding-analytics endpoints behind read:funding-analytics, and the investor-matching endpoint behind read:investors, stay outside it and may change based on open beta feedback. Choose the smallest set your integration needs. The key creation form only shows scopes available to your account.

Authentication errors

Missing or mismatched X-Client-Id headers return 400 Bad Request:

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

An invalid or expired Bearer token returns 401 Unauthorized. A valid key that lacks the required scope returns 403 Forbidden. See Errors for the common error envelope and troubleshooting guidance.

Rotation and revocation

API keys cannot be renamed, have their scopes edited, or have their secret retrieved after creation. Rotating the secret replaces a key’s client secret while keeping the same client ID, so only the secret has to be redeployed and the key’s usage history is preserved. Use Rotate secret on the key’s page in the dashboard. The previous secret stops working immediately — update your integration as soon as you rotate. Access tokens you already obtained keep working until they expire, so rotating does not cut off traffic that is already authenticated. If a secret has leaked, revoke the key instead: revocation takes effect on the next request (within five minutes) rather than at token expiry. To change a key’s scopes, create a replacement, switch your integration to it, confirm traffic on the new key, then revoke the old one. Revocation deletes the backing client-credentials application. Active-key lookups are cached, so allow up to five minutes for revocation to take effect across the service. Already-issued Bearer tokens are rejected once that change has propagated.

Usage dashboard

After making API requests, the dashboard Settings > API page shows:

Total requests: aggregated request count over time.
Request type breakdown: requests grouped as list, search, detail, map, analytics, or reference calls.
Last used: when each key was last active.

Usage is aggregated asynchronously and may require a page refresh before it appears. It is visible to accounts with the read:usage permission.

Best practices

Use least privilege: only grant scopes your integration needs.
Keep credentials server-side: the client credentials grant is not suitable for browser or mobile code where a secret cannot be protected.
Never commit secrets: use environment variables or a secrets manager.
Cache tokens: reuse an access token until shortly before it expires.
Rotate deliberately: overlap old and new credentials until traffic has moved, then revoke the old key.

HTTP client notes

The cURL examples use -g because cURL treats [ and ] as glob ranges, including inside quoted URLs. Other HTTP clients need no special option.
The cURL examples pipe the response through jq . to pretty-print it. The -sS flags silence the progress meter, which would otherwise clutter the terminal when piping, while still printing errors. If jq isn’t installed, python3 -m json.tool works as a drop-in replacement for the pipe.
Set an explicit User-Agent header when your HTTP client is a language standard library. Cloudflare sits in front of the API and blocks some default client signatures, notably Python’s urllib, with an HTML 403 (error 1010) before the request reaches the API. See Errors.

Windows shells

The Command Prompt and PowerShell examples throughout these docs follow the same conventions:

Command Prompt continues a command with ^, which must be the last character on the line. A trailing space after it breaks the continuation.
%A becomes %%A inside a .bat file. The for /f loops are written for interactive use. Double every loop variable when you save one to a script.
PowerShell’s curl is not cURL. In Windows PowerShell 5.1 it is an alias for Invoke-WebRequest, so a copied cURL command fails with unexpected argument errors. Call curl.exe explicitly when you want real cURL. The PowerShell examples avoid this by using Invoke-RestMethod.
Invoke-RestMethod parses the JSON response into objects rather than printing it. Pipe it to ConvertTo-Json -Depth 10 to see the raw shape — the default depth of 2 truncates nested fields.

Top fintech startups

Put your credentials to work in a complete, adaptable API query.

Errors

Handle expired tokens, missing scopes, validation failures, and retries.

Getting Started

Examples

Agents

Concepts

References

How credentials work

Token exchange

Token caching and refresh

Required headers

Scopes and permissions

Authentication errors

Rotation and revocation

Usage dashboard

Best practices

HTTP client notes

Windows shells

Further reading

Top fintech startups

Errors

​How credentials work

​Token exchange

​Token caching and refresh

​Required headers

​Scopes and permissions

​Authentication errors

​Rotation and revocation

​Usage dashboard

​Best practices

​HTTP client notes

​Windows shells

​Further reading

Top fintech startups

Errors

How credentials work

Token exchange

Token caching and refresh

Required headers

Scopes and permissions

Authentication errors

Rotation and revocation

Usage dashboard

Best practices

HTTP client notes

Windows shells

Further reading