Authentication

The DealMachine API uses API keys to authenticate requests. You can create keys via the Developer Settings or by using the DealMachine CLI.

API Key Format

API keys follow this format:

1dm_sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

dm_sk_ - DealMachine secret key prefix
live_ - All keys are live keys (no test environment)
The remaining 32 characters are your unique key

All API keys are live. There is no test/sandbox environment. Be mindful when testing write operations.

Making Authenticated Requests

Include your API key in the Authorization header using the Bearer scheme:

12curl https://api.v2.dealmachine.com/v1/account \
  -H "Authorization: Bearer dm_sk_live_xxx"

Request Headers

Header	Required	Description
`Authorization`	Yes	Your API key in Bearer format
`Content-Type`	Yes*	`application/json` for request bodies
`X-Request-Id`	No	Your own request ID for distributed tracing

* Required for POST, PUT, and PATCH requests with a body.

12345678const response = await fetch('https://api.v2.dealmachine.com/v1/account', {
  headers: {
    'Authorization': `Bearer ${process.env.DM_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

const { data } = await response.json();

OAuth Access Tokens

The API also supports OAuth 2.0 access tokens for third-party integrations:

1dm_at_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

OAuth tokens have scoped access based on the permissions granted during authorization. See the OAuth documentation for details.

Security Best Practices

Never expose keys in client-side code

API keys should only be used in server-side code. Never include them in JavaScript that runs in the browser, mobile apps, or any client-facing code.

Use environment variables

Store your API keys in environment variables, not in your codebase:

1export DM_API_KEY=dm_sk_live_xxx

Rotate keys if compromised

If you suspect a key has been compromised, immediately revoke it in the Developer Settings and create a new one.

Use separate keys per integration

Create separate API keys for different integrations or environments so you can revoke one without affecting others.

Getting an API Key

CLI Authentication (Recommended)

The easiest way to authenticate is using the DealMachine CLI:

12npm install -g dealmachine
dm login

This opens your browser for secure device authorization and stores credentials locally at ~/.dealmachine/config.json.

See the CLI documentation for more details.

From the App

You can also create API keys manually:

Go to Developer Settings
Click "Create API Key"
Give it a descriptive name
Copy the key immediately (it won't be shown again)

Revoking Keys

To revoke a key:

Go to Developer Settings
Find the key you want to revoke
Click "Revoke"

Revoked keys immediately stop working. Any requests using a revoked key will receive a 401 Unauthorized error.

App-hosted token exchange

Clients using OAuth authorization-server discovery should call the token_endpoint returned by /.well-known/oauth-authorization-server. The app-hosted endpoint at /api/oauth/token accepts JSON string parameters or form-encoded parameters. It rejects malformed JSON, non-string parameter values and duplicate form fields with 400 invalid_request. Optional JSON fields may be null.

A deliberate credential or grant rejection returns HTTP 400 with an OAuth error and error_description. An invalid or revoked grant uses invalid_grant. A temporary database or infrastructure failure returns HTTP 503, Retry-After: 2, and this body:

1234{
  "error": "temporarily_unavailable",
  "error_description": "Token exchange is temporarily unavailable. Please retry."
}

Keep the saved refresh token on a temporary failure and retry after the indicated delay. Do not interpret a network failure or HTTP 503 as a revoked session. An explicit invalid_grant requires a new authorization. Persist each successful rotated refresh token before attempting another rotation. App-hosted token responses include Cache-Control: no-store and Pragma: no-cache.

These status details apply to the discovered app-hosted endpoint. The REST API's /v1/oauth/token has its own documented contract.