Authentication

Every request is authenticated with an API key of your company. The key determines the company, the environment (live or sandbox) and what it may do (scopes).

Use the Authorization header with the Bearer scheme:

Authorization: Bearer xy_live_AbCd...

If your tool cannot set Authorization, use X-Api-Key: xy_live_AbCd.... If both are present, Authorization wins. A missing, invalid, revoked or expired key returns 401 invalid_api_key.

The company is never sent in the URL or the body: it comes from the key. An id of another company returns 404, exactly like a non-existent one.

Environments: live and sandbox

Key prefix	Environment	Behaviour
`xy_live_`	live	Real company data. Writes have real effects (notifications, calendar...).
`xy_test_`	test (sandbox)	Fixed example data; writes return plausible responses but nothing is stored. See Sandbox.

Both environments use the same base URL (https://api.xyago.com/v1); going live only means switching the key. Each environment has its own settings in the panel (enabled products, rate limit, IP allowlist, webhooks and signing secret).

Creating, rotating and revoking keys

An administrator manages keys in the xYago panel → API Developer → Credentials:

Create: name, environment, scopes and optional expiry. The full key is shown only once; xYago stores only a hash.
Rotate: issues a new key; the previous one keeps working for 24 hours so you can deploy the change without downtime.
Revoke: stops working immediately.

Recommendations: one key per integrated system (the panel log then shows who made each request), least-privilege scopes, keep keys in a secrets manager or environment variable and rotate them periodically or whenever you suspect a leak.

Scopes

Scope	Allows
`areas:read`	List and read areas
`areas:write`	Create areas
`employees:read`	List and read employees and import jobs
`employees:write`	Create, update, deactivate and import employees
`vacations:read`	List vacation requests and read balances
`vacations:write`	Request, approve and reject vacations
`time:read`	List time entries
`time:write`	Register time entries

Order of checks

Every request is checked in this order; the first failure is returned:

Valid API key → 401 invalid_api_key
Product enabled for the key's environment → 403 api_disabled
Endpoint enabled → 403 endpoint_disabled
Scope on the key → 403 insufficient_scope
Source IP allowed → 403 ip_not_allowed (IP allowlist)
Rate limit → 429 rate_limited (rate limits)

X-Request-Id

Every response carries X-Request-Id. You can send your own (8 to 64 characters A-Z a-z 0-9 . _ : -, e.g. your ERP job id) and it is echoed back; otherwise xYago generates one (req_...). The id appears in the panel's request log: always include it when contacting support.

curl -i "https://api.xyago.com/v1/employees?limit=10" \
  -H "Authorization: Bearer $XYAGO_API_KEY" \
  -H "X-Request-Id: siesa-sync-20260302-0001"

Transport

HTTPS only. Calls are server to server: there is no CORS, so the API cannot be called from a browser (and must not be: the key would be exposed).