Authentication

Your backend authenticates with Sentinel using client credentials. Every request carries these credentials over HTTPS, from your server. Credentials are never used in browser or mobile code.

Base URL

Sentinel provides your base URL during onboarding. Every example in this documentation uses the placeholder below, so replace it with the base URL issued to you.

https://api.sentinel.example.com

All requests are sent over HTTPS as POST with a JSON body.

Client credentials

Your client is identified and authenticated by two values, issued to you during onboarding. Include both in the JSON body of every request.

Authenticating a request

To confirm your credentials are working, call the endpoint that returns your own client details. It is read-only and a good first request.

POST https://api.sentinel.example.com/clients/find/self/clientAuth

{
  "clientUuid": "YOUR_CLIENT_UUID",
  "clientSecret": "YOUR_CLIENT_SECRET"
}

A successful response wraps your client details in a message and data envelope. Your secret is never returned; your configuration, including the webhook callback URL, is.

{
  "message": "Success",
  "data": {
    "uuid": "3f9c1e8a-1d77-4a2b-9f2e-7c6b5a4d3e21",
    "name": "Acme Financial",
    "callbackUrl": "https://your-domain.example/webhooks/sentinel",
    "settings": {
      "documents": ["passport", "emiratesId"]
    }
  }
}

Responses and errors

Responses are JSON. Successful responses are wrapped in a message and data envelope. Sentinel uses standard HTTP status codes to signal the outcome.

• 200: the request succeeded. The result is in data.
• 400: the client credentials are invalid, or the request could not be processed.
• 404: the requested resource does not exist for your client.
• 409: the request conflicts with existing data, for example a contact value already in use.
• 422: the request failed validation.

Validation and credential errors return an errors array. Some specific errors return a single message, for example a 404 with { "message": "Row not found" }.

{
  "errors": [
    { "message": "Invalid user credentials" }
  ]
}