Authentication

Every request carries an organization API key in the x-api-key header:

curl https://api.dealops.com/external/v1/products \
  -H "x-api-key: $DEALOPS_API_KEY"

There is no OAuth flow and no bearer token — the header is the whole scheme.

Getting a key

Keys are issued from Dealops settings by a user with API-key access. The key is displayed once, at creation; Dealops stores only an encrypted copy and cannot show it to you again. If you lose it, rotate to get a new one.

Give each integration its own named key. Names appear in Dealops alongside the key, so when you need to revoke one you can tell which system it belongs to.

What a key can do

A key resolves to two things: the organization it was issued for, and the user it was issued to.

• Every request is scoped to that organization. You cannot read or write another organization's data, and you cannot widen the scope by passing an organization id in a request — endpoints that once accepted one ignore it.
• The key acts as its user, within its role. Where an endpoint's rules depend on who is asking, they apply to the key's user just as they would in the app: which quotes count as "mine", and any permissions an admin granted that user by name. What the key may do beyond that comes from its own role, not the user's (see below).

Roles and scopes

Every key has a role, chosen when it is issued: admin, user or view only. The role decides the key's scopes, and every endpoint in this reference says which scope it needs (at the top of its page, and as x-required-scopes in the OpenAPI document). A key whose role lacks the scope gets 403.

Role	Can reach
View only	Reads: opportunities, pricing quotes, products, pricebooks, approval groups, deal groups, and the organization-wide list of approval requests.
User	Those reads, plus: creating and editing pricing quotes, updating opportunities, submitting and recalling approvals for the user's own quotes.
Admin	Everything: editing products and cost data, changing deal groups, managing webhooks, reading approval rules and approval-group configuration, editing locked prices, working on other users' quotes, pushing Closed Won to Salesforce, and using any pricebook.

A few endpoints return more or allow more when the key holds an extra scope (for example, product reads include inactive products and cost data for admin keys). Each endpoint's page says so.

Treat a key as a full credential for its role: store it in a secret manager, keep it server-side, and never ship it in a browser, mobile app, or anything else a customer can read.

Rotating and revoking

Both are done from the same settings screen that issued the key.

• Rotate replaces the secret and returns a new one. The previous value stops working.
• Revoke disables the key permanently.

Revocation is not instant

Key lookups are cached for up to 10 minutes, so a rotated or revoked key can keep working for that long. Plan for the delay when cutting over an integration, and if you're responding to a leaked key, treat the window as real exposure — rotate immediately and don't assume the old value is dead the moment you click.

When authentication fails

Both cases return 401 with an error body explaining which happened:

Situation	Message
No x-api-key header	API key is required. Pass it via the x-api-key header.
Header present but unknown, revoked, or malformed	Invalid API key.

A 401 is never worth retrying with the same key — fix the credential first. See Errors for the full response shape.