This reference describes endpoints that support the application JAAK ID: the field operator's session, the device's link to an enterprise and the issue of offline entitings. JAAK API Gateway under prefix /api/v1.

In integration. The service is currently being deployed and examples reflect the actual contract but environment and credentials URLs will be confirmed during integration.

Authentication

The operator gets a JWT token at login. That token (7 day) is sent as Authorization: Bearer <token> The endpoint of login and that of public keys are public and the others require token.

Errors format

All mistakes give back the same JSON body:

{
  "eventId": "57845ce0-9360-4f00-8711-c9fe1a59824e",
  "statusCode": 401,
  "errorCode": "0101",
  "message": "invalid credentials"
}

Code	HTTP	Meaning
`0002`	400	Invalid application
`0101`	401	Invalid credentials or inactive operator
`0102`	401	Token absent, malformed, expired or revoked
`0103`	409	Unbound device (as requested)
`0104`	404	Unknown Company Code
`0105`	404	Token QR nonexistent
`0106`	410	Token QR expired
`0107`	409	Token QR already used

Operator's meeting

POST / api / v1 / operator / login

Public. Authors to the operator and issues session token (7 days).

Request

{
  "username": "operador.gutierrez",
  "password": "••••••••••",
  "device_id": "BRG-14"
}

Answer 201

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "ttl_millis": 604800000,
  "server_epoch_millis": 1786060816265,
  "operator": {
    "id": "6f1e8a2c-0000-4000-8000-000000000001",
    "username": "operador.gutierrez",
    "display_name": "A. Gutiérrez",
    "brigade": "Brigada Xochimilco"
  },
  "org": { "code": "BNRT-4K9M", "name": "Banorte Services", "initials": "BN" }
}

ttl_millis and server_epoch_millis allow the app to anchor session validity to the server's watch and not to the device's.

POST / api / v1 / operator / session / refresh

Requires Bearer. Re- emits the current token (revalidation sliding, without re-applying for credentials). Reforms the same body as login.

Session KYC

POST / api / v1 / operator / kyc / session

Requires Bearer. Create Session KYC from a field-caught enrollment. powerful by enrollment_id: repeat call returns the same session.

Request

{ "enrollment_id": "6deb3231-719e-4230-bd45-bc761a69f2c1", "folio": "ENR-0001" }

Answer 201

{
  "session_id": "ba73c331-fc0f-48f1-8976-bb190022ea3c",
  "trace_id": "4d0b27ddf6a534849969b96a971bf6ed"
}

The trace_id It's the identifier with which the rest of the check pipeline are correlated while synchronizing.

Unit link

POST / api / v1 / devices / qr

Requires Bearer. The operator (or manager from JAAK Console) emits a single-use QR token, valid 15 minutesto link a device to the company.

Answer 201

{
  "qr_token": "c5c910da83640cbb1a933e47",
  "org_code": "BNRT-4K9M",
  "expires_at_epoch_millis": 1786062428253,
  "qr_payload": "jaak-org:c5c910da83640cbb1a933e47"
}

qr_payload That's exactly what the app codifies at QR and reads while scanning.

POST / api / v1 / devices / link

Requires Bearer. Fits the device to the company. Company code or token QR.

Request (by code)

{ "code": "BNRT-4K9M", "device_id": "BRG-14", "platform": "android", "model": "Pixel 7" }

Request (by QR)

{ "qr_token": "c5c910da83640cbb1a933e47", "device_id": "BRG-99", "platform": "android" }

Answer 200

{
  "org": {
    "code": "BNRT-4K9M",
    "name": "Banorte Services",
    "initials": "BN",
    "control_lists": ["OFAC", "SAT", "RENAPO", "INE", "Interpol"]
  },
  "linked_at": "2026-08-07T00:12:08Z"
}

A previously used QR token returns 0107One expired, 0106.

Units offline

POST / api / v1 / devices / entitlement

It requires Bearer and related device. It emits a signed offline license that enables SDK Unconnected capture. If the device isn't tied back 0103.

Request

{ "device_id": "BRG-14" }

Answer 201

{
  "entitlement": {
    "payload_b64": "YmFub3J0ZXxCUkctMTR8MTc4NjY2NTYzNzQxMA==",
    "signature_b64": "AqDBbBwzcN+rsF27zsJpK0mRtZ9RdwWL93GxKelYeZo...",
    "key_id": "2dc5eaef",
    "tenant_id": "banorte",
    "device_id": "BRG-14",
    "expires_at_epoch_millis": 1786665637410
  }
}

The payload_b64 decodifies the canonical text tenantId|deviceId|expiresAtEpochMillis (e.g. banorte|BRG-14|1786665637410). The app verifies the signature Ed25519 at local level with the corresponding public key before relying on the entitlement.

NET / api / v1 / operator / keys

Public. Reforms public keys Ed25519 with which to check the entries.

{
  "keys": [
    { "key_id": "2dc5eaef", "public_key_b64": "Xb5JC9Yhnog0uEPtea6k2ntsyk36eAjctnGoT/gbOYo=", "alg": "Ed25519" }
  ]
}

The key by key_id (also present at the tipple) to allow rotation.