Authentication

Every call to the Syntic API must prove who is calling and which organization pays for it. You do this with a single header holding a private credential.

Authorization: Bearer sk_live_3f9c...

The word Bearer is matched without regard to case. A request with no credential at all is answered with 401 unauthenticated.

Credentials the API accepts

Credential	Looks like	Where it comes from	Accepted
Private API key	`sk_live_` followed by 64 hex characters	Console, Settings → API Keys, kind Private	Yes
Syntic Code key	`sk_syntic_...`	Created for the Syntic Code CLI	Yes
Syntic Code sign-in token	A signed access token	Issued when you sign in to Syntic Code	Yes
Public API key	`pk_live_...`	Console, kind Public	No: `403 public_key_rejected`

For your own applications, use a private sk_live_ key. Syntic Code keys and sign-in tokens exist so the Syntic Code CLI can use the same endpoint; your own code never has to deal with them. How Syntic’s apps obtain sign-in tokens is described in Sign in with Syntic.

Create a private key

Open the key settings

Create the key

Choose Private, give the key a name that says where it will run (for example billing-service-prod), and optionally add allowed origins (see below). If you or your organization has multi-factor authentication turned on, you are asked to confirm it again before the key is created.

Copy the secret straight away

The full secret is shown once. Syntic stores only a hash of it plus the first few characters, so a lost secret cannot be shown again; create a new key instead.

Store it outside your code

Keep the secret in an environment variable or your secrets store. The examples in these docs read it from SYNTIC_API_KEY:

export SYNTIC_API_KEY="sk_live_..."

Step-by-step screenshots and team permissions are covered in Get an API key and Managing API keys.

Which organization pays

Each key is tied to the organization where it was made. Every request made with it draws on that organization’s plan allowance and usage credits, and uses that organization’s plan to decide which models are available. A key keeps working only while:

the account that created it is enabled, and
that account is still an active member of the key’s organization, and
the organization itself is available.

When any of these stops being true, requests fail with 403 (see the table below) even though the key was never revoked. If a team member leaves, replace the keys they created.

Origin allowlists

A private key can carry a list of website origins it may be used from. This is a guard for keys that end up in browser code.

Allowlist	What happens
Empty (the default)	No origin check. The key works from servers, scripts and browsers.
One or more entries	The request must name an origin in the list, or it is refused with `403 origin_not_allowed`.

How the check works:

The API reads the Origin request header. If there is none, it falls back to the origin part of the Referer header.
Only scheme, host and port are compared; any path is ignored. Default ports are dropped, so https://shop.example.org and https://shop.example.org:443 are the same origin. Upper and lower case do not matter.
An entry such as https://*.example.org matches any subdomain (https://eu.example.org, https://a.b.example.org) but not https://example.org itself. Add the bare domain as its own entry if you need it.
A bare host such as shop.example.org is treated as https://shop.example.org.
When a key has an allowlist and the request carries neither header, it is refused. curl and most server code send no Origin, so an allowlisted key is effectively browser-only.

An origin allowlist limits where a key is accepted, but a determined person can still forge headers outside a browser. Treat it as a second line of defence, never as a reason to publish a key.

Revoking and expiry

Revoke a key in Settings → API Keys as soon as it may have leaked. Requests with it then fail with 401 revoked_api_key. A key that has passed its expiry date fails with 401 expired_api_key. Creating and revoking keys is recorded in the organization’s audit log.

Authentication errors

All of these return the error envelope, for example:

{
  "error": {
    "type": "authentication_error",
    "code": "revoked_api_key",
    "message": "This API key was revoked. Create a new one in Settings → API keys.",
    "param": null,
    "request_id": "req_6f1c2a9e0b7d4c3a8e5f1b2d"
  }
}

Status	`type`	`code`	Cause	What to do
401	`authentication_error`	`unauthenticated`	No `Authorization` header, or an empty one.	Send `Authorization: Bearer <key>`.
401	`authentication_error`	`invalid_api_key`	The key is not recognised or is inactive.	Check for copy errors or create a new key.
401	`authentication_error`	`revoked_api_key`	The key was revoked.	Create a new key.
401	`authentication_error`	`expired_api_key`	The key is past its expiry date.	Create a new key.
401	`authentication_error`	`invalid_token`	A Syntic Code sign-in token failed verification or has expired.	Sign in to Syntic Code again.
403	`permission_error`	`public_key_rejected`	A `pk_live_` key was sent.	Use a private `sk_live_` key.
403	`permission_error`	`origin_not_allowed`	The key has an allowlist and the request’s origin is missing or not on it.	Call from an allowed origin, or edit the key’s allowed origins.
403	`permission_error`	`insufficient_scope`	The credential is not allowed to run model requests. The body also has `"required": "user:inference"`.	Use a private key.
403	`permission_error`	`org_membership_required`	The key’s owner is no longer an active member of its organization.	Create a key under a current member.
403	`permission_error`	`account_disabled`	The account that owns the credential is disabled.	Contact your organization’s admin.
403	`permission_error`	`org_unavailable`	The credential’s organization is not available.	Contact Syntic support.
503	`service_unavailable_error`	`authorization_unavailable`	The credential could not be checked just now.	Retry after a short wait.

Good practice

Use one key per application and environment, so revoking one leaves the others running.
Never commit keys to source control or paste them into tickets or chat.
Rotate keys regularly: create the new key, deploy it, then revoke the old one.
Watch the Usage & cost page for traffic you do not recognise; see Usage & cost.

Overview Chat completions

Was this page helpful?