Skip to main content
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.
The response includes the token and its lifetime:
The audience value (https://api.dealroom.app) is an OAuth2 identifier, not necessarily a URL you call. It may match the API base URL (https://api.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.

Required headers

Every request authenticated with an API key must include two headers: 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.
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: Analytics scopes: 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:
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.

Further reading

Top fintech startups

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

Errors

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