Access control

Goal: have your access control system (turnstiles, card readers, kiosks) record check-ins in Kinmu in real time.

Required scopes: org:fichajes:write (record) and org:fichajes:read (query).

Record a check-in

POST /v1/check-ins records an event on behalf of an employee. It is persisted with source=api, is audited and respects workday validations (no rule bypass).


curl -s -X POST "$KINMU_BASE_URL/check-ins" \
  -H "Authorization: Bearer $KINMU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "employee_id": "a1b2c3d4-…",
    "type": "in",
    "timestamp": "2026-07-08T08:00:00Z",
    "location_id": "loc-uuid",
    "note": "Main door access"
  }'

Body fields:

Field	Required	Notes
`employee_id`	Yes	Public UUID of the employee.
`type`	Yes	`in`, `out`, `break_start` or `break_end`.
`timestamp`	Yes	ISO 8601 in UTC.
`location_id`	No	Site where the check-in occurs.
`note`	No	Free text (e.g. the reader’s identifier).

201 response:


{
  "id": "ci-uuid",
  "employee_id": "a1b2c3d4-…",
  "type": "in",
  "timestamp": "2026-07-08T08:00:00Z",
  "location": { "id": "loc-uuid", "name": "Madrid Office" },
  "source": "api",
  "validated": true,
  "created_at": "2026-07-08T08:00:01Z",
  "updated_at": "2026-07-08T08:00:01Z"
}

Use an Idempotency-Key on every check-in. Turnstiles retry on network outages; with an idempotent key you avoid recording the same access twice. Resending the same key returns the original check-in; reusing it with a different body gives 409.

Map your employees

Your access system identifies people by card or PIN; Kinmu by employee_id (UUID). Build the mapping once and refresh it periodically:

Download the employees and their structure


curl -s "$KINMU_BASE_URL/employees?status=active&limit=100" \
  -H "Authorization: Bearer $KINMU_API_KEY"
curl -s "$KINMU_BASE_URL/locations" -H "Authorization: Bearer $KINMU_API_KEY"

Store the `card → employee_id` and `zone → location_id` mapping

Use email or a field from your master record to match people; store the Kinmu UUIDs.

Refresh with `updated_since`

Re-read only what changed: GET /v1/employees?updated_since=<last sync>.

Query check-ins

To reconcile, read the events with a required range of ≤ 92 days:


curl -s "$KINMU_BASE_URL/check-ins?employee_id=a1b2…&from=2026-07-01&to=2026-07-08" \
  -H "Authorization: Bearer $KINMU_API_KEY"

Want to react in real time to every check-in (for example, for a presence board)? Subscribe to the checkin.created event with webhooks instead of polling.

Common errors

Situation	Response
Missing `org:fichajes:write`	`403 invalid_scope`
`timestamp` out of range or invalid `type`	`422 validation_failed` (with `errors`)
Retry with same `Idempotency-Key` and different body	`409 idempotency_conflict`
Employee from another company	`404 not_found`