Getting Started

This guide orients a new integration partner: the API surface, the two authentication scopes, the response format decision, and where to go next.

Base URL

Every example uses https://api.example.com as a placeholder. Replace it with the API_DOMAIN your Defentry account manager assigned to your client.

1. Understand the two scopes

Almost every call uses one of two bearer tokens:

Token	Obtained via	Acts as	Typical use
CRM token	`POST /api/v1/crm/auth/login`	Your service account	Create/administer accounts, manage watchlists by account id, read alarms
App token	`POST /api/v1/sso/token`	A single end user	Self-service profile, own watchlists, Online Data

If you are administering accounts from your backend, you want the CRM token. Use an app token only for actions that must happen as the user.

2. Get your credentials

Your account manager provisions:

An API_DOMAIN for your white-label client.
A first CRM user — use it to create a service account in the CRM portal; your backend authenticates as that service account.
SSO credentials (client_id / client_secret) if you need app tokens.

See Onboarding & service account for the full setup.

3. Authenticate

http

POST /api/v1/crm/auth/login
Content-Type: application/json

{ "username": "your-service-account@partner.com", "password": "your_password" }

Send the returned token as Authorization: Bearer {token} on subsequent calls.

4. Pick your response format

Choose per request with the X-API-Version header:

X-API-Version: 2026-06-12 → standardized (ISO-8601 datetimes, JSON booleans, one error envelope)
header omitted → legacy format

Read Legacy → Standardized migration and Response & Error Conventions before writing parsing logic. The API Explorer shows both formats with its version selector.

5. Follow the flows

Work through the Integration flows in order:

Getting Started ​

1. Understand the two scopes ​

2. Get your credentials ​

3. Authenticate ​

4. Pick your response format ​

5. Follow the flows ​

Next steps ​