Onboarding & Service Account

This is where every integration starts. By the end you will hold a CRM token that authenticates your backend as a service account, ready to create and manage customer accounts.

Base URL

All examples use https://api.example.com. Replace it with the API_DOMAIN your Defentry account manager assigned to your client.

1. Receive your first CRM user

Defentry provisions your first CRM user for you and shares the credentials through your account manager. This first user is a real, interactive login — treat it as a break-glass administrator, not as the credential your servers use day to day.

2. Create a service account

Sign in to the Defentry CRM portal with your first user and create a dedicated service account for your integration:

• Give it a clear name (e.g. acme-backend-integration).
• Grant it only the permissions your integration needs.
• Store its credentials in your secret manager — your backend will use these, not the human admin's.

Why a separate service account

Rotating or revoking the integration credential must never lock out your human administrators, and vice versa. The service account is created in the portal; there is no public API endpoint for provisioning CRM users.

3. Log in to get a CRM token

Authenticate the service account to receive a bearer token:

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

{
  "username": "acme-backend-integration@partner.com",
  "password": "your_service_account_password"
}

Response (200):

{
  "token": "Xk3n9qL0w5Yb7cVt2RfH8sJd4MpA6eGuZ1iNoQyT",
  "expires_at": "2026-10-09T11:42:19+02:00",
  "expires_in": 3600
}

Send Authorization: Bearer {token} on every CRM call. token is an opaque 40-character string. Do not split it on |. Every login creates a new token. It lasts 60 minutes, or 24 hours (expires_in 86400) when you pass "keep_logged": true. Use expires_at from this response. Log in again when a call returns 401.

4. Two-factor authentication (interactive users only)

Service accounts do not use 2FA

2FA applies to interactive human CRM logins (such as your first admin user in the portal). A service account is not enrolled in 2FA — its login returns a usable token directly, so your backend never has to handle a 2FA challenge.

For interactive human users, the challenge is completed with:

POST /api/v1/2fa/setup
Authorization: Bearer {crm_token}

POST /api/v1/2fa/verify
Authorization: Bearer {crm_token}
Content-Type: application/json

{ "code": "123456" }

5. Password recovery

Human administrators can recover access without involving Defentry support:

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

{ "email": "admin@partner.com" }

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

{ "token": "emailed-token", "password": "new_password", "password_confirmation": "new_password" }

6. Log out

End a session explicitly when you are done (for example when rotating credentials):

POST /api/v1/crm/logout
Authorization: Bearer {crm_token}

Next step

Create and administer customer accounts with your CRM token.