Authentication

Every request to the Synex API authenticates with a secret API key sent as a bearer token. Keys are pinned to a team, carry a set of abilities, and can be restricted to specific ontologies — so you can hand an integration exactly the access it needs and nothing more.

API keys

Create and revoke keys from API Keys in the Synex application. Send the secret in the Authorization header on every request:

Authorization header

curl https://api.synexcloud.com/v1/me \
  -H "Authorization: Bearer synex_sk_..."

The secret (synex_sk_...) is shown once, at creation — only a hash is stored. Treat keys like passwords: keep them out of client-side code, repositories, and logs. If a key leaks, revoke it and issue a new one.

Team pinning

Every key is pinned to the team it was created in, and all requests act on that team. Switching teams in the web app never changes what a key can see. If the key's creator leaves the team, the key stops working and requests fail with 401 api_key_team_revoked.

Abilities

A key carries a set of abilities, and each endpoint requires one. A request without the required ability fails with 403 insufficient_permissions.

Name
templates:read / templates:write
Type
ability
Description
List and read templates · create, edit, fork, complete, and delete them.
Name
ontologies:read / ontologies:write
Type
ability
Description
List and read ontologies · instantiate them from completed templates.
Name
passports:read / passports:write
Type
ability
Description
Read, list, and download QR codes · create, update, and delete passports.
Name
compositions:read / compositions:write
Type
ability
Description
Read presentation layouts · create and update them.
Name
files:write
Type
ability
Description
Upload files used by mass imports.
Name
imports:read / imports:write
Type
ability
Description
Inspect imports and their rows · start imports and retry failed rows.
Name
audit:read
Type
ability
Description
Query the audit log (the key owner must be a team admin or owner).
Name
lab:read / lab:write
Type
ability
Description
Run queries, DSL tools, runs, and usage · execute transforms and rollbacks (admin or owner).

Ontology scopes

Abilities that touch passport data — passports:*, compositions:*, and imports:* — can be restricted to specific ontologies when the key is created. A scoped key:

can act only on resources inside its listed ontologies; anything else fails with 403 ability_not_scoped_to_resource;
cannot use list endpoints that span the whole team (for example GET /v1/imports) — fetch those resources by id instead.

Use scoped keys for integrations that should only ever see one product line.

Role-gated endpoints

Two areas additionally require the key's owner to be a team admin or owner at request time. Revoking the role instantly disables these calls, regardless of the key's abilities:

the audit log (GET /v1/audit_events);
Lab transforms and rollbacks.

GET/v1/me

Inspect the current key

Returns the context the key is acting in — its pinned team, the abilities it carries, and any ontology scopes. Call this to verify a key before relying on it, or to discover what an integration is allowed to do.

This endpoint requires only a valid key (no specific ability).

Request

GET

/v1/me

curl https://api.synexcloud.com/v1/me \
  -H "Authorization: Bearer $SYNEX_API_KEY"

Response

{
  "object": "api.key",
  "team": { "id": 42, "name": "Acme Batteries" },
  "abilities": [
    "passports:read",
    "passports:write",
    "imports:read",
    "imports:write"
  ],
  "scopes": {
    "ontologies": ["ontology_00a1b2c3d4e5f607"]
  }
}