API reference

Arkyc exposes four surfaces, all under a global /api prefix:

• Public Project API: your backend, authenticated with a project secret key (sk_…). Create and manage verification sessions.
• Client / Widget API: the browser widget, authenticated with a short-lived client token. Submit captures and complete a session.
• Dashboard API: the management UI, authenticated with a bearer JWT and gated by permissions.
• Auth: dashboard sign-in (/v1/auth/...), summarized on the Dashboard API page.

Base URL

https://<your-api-host>/api

In local development that's http://localhost:3100/api.

Response envelope

Every response uses a consistent envelope:

{
  "status": "success",
  "message": "Human-readable message",
  "code": 200,
  "data": {}
}

List endpoints add a pagination meta:

{
  "status": "success",
  "code": 200,
  "data": [],
  "meta": { "current_page": 1, "per_page": 15, "total": 42 }
}

Errors carry the same envelope with status: "error". Validation failures (422) include a field-keyed errors object:

{
  "status": "error",
  "message": "The given data was invalid.",
  "code": 422,
  "errors": { "email": ["The email field is required."] }
}

Common status codes: 200 OK, 201 Created, 202 Accepted, 401 Unauthorized, 403 Permission denied, 404 Not found, 409 Conflict, 422 Validation error.

Error codes

Errors Arkyc deliberately raises include a stable error field contract that tell the client exactly what went wrong.

{
  "status": "error",
  "code": 401,
  "error": "session_expired",
  "message": "Session expired"
}

This disambiguates cases that share an HTTP status, a 401 could be an expired session, a bad client token, or an invalid API key:

error	HTTP	Meaning
missing_client_token	401	No client token on a Client/Widget API request.
invalid_client_token	401	The client token doesn't resolve to a session.
session_expired	401	The session (and its client token) has expired.
missing_api_key	401	No secret key on a Public Project API request.
invalid_api_key	401	The secret key is unknown, revoked, or expired.
invalid_workflow	422	workflow_id is unknown for this organization.
invalid_webhook	422	The referenced webhook endpoint is unknown/invalid.

Responses without an error field are unexpected/unhandled errors (treat them as generic by code); only the errors above are part of this contract.

Authentication at a glance

Surface	Header
Public Project	Authorization: Bearer sk_… (or X-Api-Key: sk_…)
Client / Widget	X-Client-Token: <token> (or Authorization: Bearer …)
Dashboard	Authorization: Bearer <jwt>

List endpoints accept a per_page query parameter; the Public/Client surfaces accept multipart/form-data for image uploads.