Home / Developers

Developers

One simple REST API. Send an image or a frame, get a structured JSON result back. Every check is a single HTTPS request authenticated with your API key or an OAuth2 bearer token.

Base URL & authentication

Your base URL and credentials are issued when you get access. Every request goes to your dedicated base URL — https://api.eaglecheck.com.au/YOUR_CLIENT_ID/v1/, where YOUR_CLIENT_ID is the identifier we assign you and v1 is the API version. Your API is provisioned with one of two authentication methods, chosen when you're set up: a simple API key, or OAuth2 client-credentials. All requests and responses are JSON.

Option A — API key. Send your key in the x-api-key header on every request. Simplest to get started; keep it server-side.

POST https://api.eaglecheck.com.au/YOUR_CLIENT_ID/v1/detect-faces
x-api-key: YOUR_API_KEY
Content-Type: application/json

Option B — OAuth2 (client credentials). Exchange your client id and secret for a short-lived bearer token, then send it as an Authorization: Bearer header. The secret stays on your server and can be rotated without redeploying your app — the recommended option for server-to-server use.

# 1. Get a token (valid ~1 hour) from your issued auth endpoint
curl -X POST https://YOUR_AUTH_DOMAIN/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=client_credentials&scope=rs/detect"

# response
{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 3600 }
# 2. Call any endpoint with that token
POST https://api.eaglecheck.com.au/YOUR_CLIENT_ID/v1/detect-faces
Authorization: Bearer eyJ…
Content-Type: application/json

Cache the token until it expires rather than requesting one per call.

Images are passed as a base64 data URI in imageContent. Use JPEG or PNG, up to 5 MB; downscale large photos client-side (we recommend a longest edge of ~1600 px).

curl https://api.eaglecheck.com.au/YOUR_CLIENT_ID/v1/detect-faces \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "imageContent": "data:image/jpeg;base64,/9j/4AAQ..." }'

Age & face attributes

POST /detect-faces — estimates age and returns gender, attributes and ranked emotions for each detected face.

// Request   (threshold is optional - flags faces estimated under that age)
{ "imageContent": "data:image/jpeg;base64,…", "threshold": 18 }

// Response
{
  "faces": [
    {
      "ageRange": { "low": 26, "high": 34 },
      "possiblyUnderThreshold": false,
      "gender": { "value": "Female", "confidence": 99.4 },
      "attributes": {
        "smile": { "value": true, "confidence": 92.1 },
        "eyeglasses": { "value": false, "confidence": 98.0 }
      },
      "emotions": [
        { "type": "happy", "confidence": 88.2 },
        { "type": "calm", "confidence": 7.5 }
      ]
    }
  ]
}

The model returns an age range; the midpoint is the usual single estimate. Thresholds (18+, 21+, Challenge-25) are yours to apply, or act on the raw range.

Face matching

POST /compare-faces — compares two faces and returns a similarity score against your configured threshold.

// Request
{ "sourceImage": { "imageContent": "data:image/jpeg;base64,…" },
  "targetImage": { "imageContent": "data:image/jpeg;base64,…" } }

// Response
{ "isMatch": true, "threshold": 80, "matches": [ { "similarity": 99.1 } ] }

Text detection (OCR)

POST /detect-text — reads lines of text from an image.

// Request
{ "imageContent": "data:image/jpeg;base64,…" }

// Response
{ "lines": [ { "text": "MAIN ST", "confidence": 99.2 } ] }

Label detection

POST /detect-labels — identifies objects, scenes and concepts.

// Request
{ "imageContent": "data:image/jpeg;base64,…" }

// Response
{ "labels": [ { "name": "Car", "confidence": 98.4 },
             { "name": "Person", "confidence": 95.1 } ] }

PPE detection

POST /detect-ppe — detects protective equipment (face, head and hand covers) per person.

// Request
{ "imageContent": "data:image/jpeg;base64,…" }

// Response
{ "persons": [
    { "id": 0,
      "bodyParts": [
        { "name": "HEAD",
          "equipment": [ { "type": "HEAD_COVER", "confidence": 97.3,
                           "coversBodyPart": { "value": true } } ] }
      ] }
] }

Content moderation

POST /detect-moderation — flags unsafe or inappropriate content, with each label's top-level category.

// Request
{ "imageContent": "data:image/jpeg;base64,…" }

// Response
{ "moderationLabels": [
    { "name": "Weapons", "parentName": "Violence", "confidence": 92.3 }
] }

Face liveness

Liveness is the one check that needs both a back end and a front end. You don't POST an image and get a result, a browser SDK runs the guided capture and streams the video straight to the liveness service. Your API only brackets it:

  1. Back end calls POST /liveness/session to start a session and get a sessionId plus short-lived credentials.
  2. Browser SDK (our FaceLivenessDetector component) opens the camera, runs the face-in-oval challenge, and streams the video directly to the liveness service, not through your API.
  3. Back end calls GET /liveness/result with the sessionId to read the outcome.
// 1. POST /liveness/session   body: { "challengeType": "FaceMovementAndLightChallenge" }
{ "sessionId": "…", "region": "…", "credentials": { /* short-lived, for the SDK */ } }

// 2. Browser: the FaceLivenessDetector SDK runs the capture + streaming

// 3. GET /liveness/result?sessionId=…
{ "sessionStatus": "SUCCEEDED", "isLive": true, "confidence": 98.7 }

Challenge type. POST /liveness/session takes an optional challengeType in the body, which we pass straight through to the liveness service. Two values are supported:

  • FaceMovementAndLightChallenge (default) — face movement plus a coloured-light sequence.
  • FaceMovementChallenge — movement only, no flashing light; use this where photosensitivity is a concern.

Omit the field to get the default; any other value returns 420 (Invalid challengeType). The chosen type is echoed back in the response.

The guided capture runs entirely in the browser and streams directly to the liveness service — the video never passes through or is stored by eaglecheck. Liveness therefore can't run from a server-to-server integration alone; it needs our web SDK embedded in your page. See it working on the live demo.

Errors

Errors return a JSON body with a message. Common statuses: 200 success, 400/420 invalid request or image, 403 missing or invalid API key, 429 rate limit exceeded, 500 unexpected error.

{ "message": "Invalid image content" }

Notes

  • Images and video are processed to produce the result and then discarded; nothing is retained.
  • Most checks run in Australia; the liveness video stream is processed overseas (see the Privacy Policy).
  • Rate limits apply per API key; contact us if you need higher throughput.

Keeping your credentials secure

Treat your API key (and OAuth client secret) like a password: keep it on your server, never in client-side code. Anything shipped to a browser or mobile app — including environment variables baked into a frontend bundle — can be extracted by anyone using the app, so call eaglecheck server-to-server from your own backend.

browser / app  →  YOUR backend (holds the key)  →  eaglecheck API
                  the credential stays server-side
  • Have a backend? Store the key/secret there and proxy requests through it. For server-to-server auth, OAuth2 client-credentials is ideal — the secret never leaves your server and you can rotate it without redeploying your frontend.
  • Browser-only app (SPA, no backend)? Don't embed the key. Put a thin proxy (even a single function) in front to hold it, use per-user login (OAuth authorization-code + PKCE), or mint short-lived, scoped tokens from a small backend.
  • Liveness already models this: your backend calls /liveness/session and the browser SDK only ever receives short-lived, scoped credentials — never your API key.

Our public demo deliberately calls the API straight from the browser with a contained, rate-limited demo key, so it needs no backend. Don't copy that pattern for production — use a server-side credential instead.

Get API access Try the live demo →

eaglecheck — one API for age, identity and image checks.