Authentication

All Integration API endpoints require authentication. The recommended mechanism for external integrations is the OAuth 2.0 client credentials flow with Microsoft Entra ID: your application exchanges its credentials for a short-lived access token at Microsoft, then presents that token to the Integration API as a bearer token.

Unexus never sees or stores your credentials — tokens are issued by Microsoft and validated by Unexus against Microsoft’s published signing keys.

sequenceDiagram
    participant App as Your application
    participant Entra as Microsoft Entra ID
    participant API as Unexus Integration API

    App->>Entra: POST /oauth2/v2.0/token<br/>(client id + secret, scope)
    Entra-->>App: access_token (~1 hour)
    App->>API: Request with Authorization: ******
    API->>API: Validate signature, audience, issuer
    API-->>App: 200 OK
    Note over App: Cache the token and reuse it<br/>until shortly before expiry

Onboarding (one-time)

Before your first call, two things must be configured:

1. Your side — register an application in your Microsoft Entra ID tenant (Azure portal → App registrations → New registration). Note the Application (client) ID and create a client secret.
2. Unexus side — your Unexus contact provides you with the target application ID (the scope value below) and registers your tenant as a trusted audience on the installation.

Requesting a token

Request a token from Microsoft — not from Unexus:

POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={your-application-id}
&client_secret={your-client-secret}
&scope={unexus-application-id}/.default

Response:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..."
}

Caution

The scope must be {unexus-application-id}/.default — this makes the token’s audience (aud claim) match what the Integration API accepts. Using any other scope results in 401 Unauthorized.

Using the token

Send the token in the Authorization header of every API request:

GET /api/v1/webhooks/subscriptions
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs...

Token lifetime and caching

• Tokens are valid for roughly one hour (expires_in is in seconds).
• Cache the token and reuse it until shortly before expiry. Do not request a new token per API call — Microsoft throttles token endpoints.
• When a request returns 401, obtain a fresh token and retry once.

Testing with Postman

1. Open a request → Authorization tab → Type OAuth 2.0.
2. Configure a new token:
   • Grant type: Client Credentials
   • Access Token URL: https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
   • Client ID / Client Secret: from your app registration
   • Scope: {unexus-application-id}/.default
3. Click Get New Access Token, then Use Token. Postman attaches the header and refreshes the token for you.

Alternative: trusted server access

For on-premise, server-to-server integrations, the API also accepts requests from explicitly configured trusted network addresses without a bearer token. This is configured per installation by Unexus and is not available for cloud/external integrations. Ask your Unexus contact if you believe this applies to your setup.

Security notes

• Store the client secret in a secret manager (Azure Key Vault or equivalent). Never commit it to source control.
• Rotate secrets periodically; Entra ID supports overlapping secrets so rotation requires no downtime.
• Use separate app registrations for test and production.