Authentication
Authenticate with the Syntext API using a session JWT or a project-scoped API key.
Almost every Syntext API endpoint requires authentication; a few public ones (such as the published schemas, search, invitations and the AI assistant's chat endpoints) don't, and their pages say so. There are two ways to authenticate, and which one you use depends on who is calling:
| Caller | Credential | Use it for |
|---|---|---|
| A person in the dashboard | Session JWT | Interactive use — the dashboard handles this for you |
A person using the stx CLI | Session JWT from stx login | Running CLI commands as yourself |
| A machine, script, or CI job | Project API key (stx_...) | Automated builds and deploys |
Both are presented in the same header, so most clients need no special handling:
Syntext tells the two apart by the stx_ prefix. Anything starting with stx_ is verified as an API key; everything else is verified as a JWT.
API keys
What a key is scoped to
An API key is scoped to exactly one project. It is not an organization-wide credential, and it is not tied to the user who created it.
This has two consequences worth being explicit about:
404 Not Found — Syntext does not confirm whether the other project exists.If you automate several projects, create one key per project.
Because a key is bound to a single project, the project id in the request path must match the key's project. There is no "current project" inferred from the key.
Scopes
Each key carries one scope, granting everything below it:
| Scope | Can do |
|---|---|
read | Read builds, build logs, export bundles and version diffs, plus hosted content status, files, history and revisions, and imported OpenAPI specs and endpoints |
build | Everything in read, plus trigger and cancel builds, deploy, promote and roll back deployments, publish hosted content, and import or remove OpenAPI specs |
full | Everything in build, plus restore a content revision and import content |
Pick the narrowest scope that works. A CI job that only ships docs needs build; a status dashboard needs read.
Using a key below the required scope returns 403 Forbidden, with a message naming the scope that was needed.
Creating a key
Keys are created per project, from the dashboard under your project → Settings › API keys (the full key is shown once, right after creation), or via the API:
The full key is returned only once, at creation. Syntext stores only a one-way hash of it plus the non-secret prefix, so a lost key cannot be recovered — rotate it instead.
Managing keys (create, list, rotate, delete) always requires a session JWT. An API key cannot create, rotate, or list API keys, so a leaked key cannot be used to mint more.
expiresInDays is optional; omit it for a key that does not expire.
Key format
The prefix is stored in plain text and shown in the dashboard so you can identify a key without revealing it.
Using a key
Send it as a Bearer token:
An X-API-Key header is also accepted, if that suits your client better:
The stx CLI sends the Authorization: Bearer form. Pass a project API key to stx deploy, stx build or stx dev with --token stx_.... stx login --token only accepts a session token, not an API key.
A session JWT is not enough on its own
Authenticating proves who you are. It does not, by itself, grant access to a project.
Every project-scoped endpoint — anything under /v1/projects/{projectId} — additionally checks that you are a member of the organization that owns that project. The two credentials enforce this differently, but the outcome is the same:
404 Not Found.404 Not Found; a project that exists but belongs to an org you do not belong to returns 403 Forbidden with the forbidden code — see Errors.Syntext returns 404 rather than 403 for a project you have no relationship with, so the API does not confirm whether another organization's project id exists.
A small, deliberate set of endpoints is public and needs no credential at all, because the rendered documentation site calls them from a visitor's browser:
| Public surface | Endpoints |
|---|---|
| Analytics beacons | POST /analytics/pageview, /analytics/search, /analytics/chat, /analytics/playground, /analytics/funnel |
| Site search | GET /search, GET /search/popular |
| AI assistant | the chat endpoints |
| Community widgets | page and section feedback, annotation reads and upvotes, discussion reads |
On a private site (password, invite-only or SSO), search, the assistant and feedback answer only through the doc site itself — a direct call gets 403 FORBIDDEN.
Everything else under /v1/projects/{projectId} requires both a credential and org membership — including semantic search and the /ai/* endpoints, GET /openapi and /openapi/endpoints, tutorials, and the dashboard API playground (/playground/*).
Outside projects, a few account endpoints are public too, because the token or file name in the URL is the credential: Get Invitation, Decline Invitation, avatar images (GET /v1/auth/avatars/{userId}/{file}, see Upload Avatar), and the unsubscribe link in Syntext's emails (Get Unsubscribe Link and Unsubscribe). Signing in is public by nature — Register, Log In and Sign In with GitHub.
Roles
Membership is not the end of the check. Each member has a workspace role, owner > admin > member. Changing a project, managing API keys, domains, site access control and outbound webhooks, minting audience access codes, Slack bot settings, workspace settings and member roles, billing history, and most collaboration configuration need admin or owner; deleting a workspace and transferring ownership need owner. A member gets 403 forbidden with details.requiredRole and details.currentRole. The full list is in Errors → Admin-only endpoints.
Connecting a GitHub App installation
A project reads and commits to its repository through a GitHub App installation, and the installation must be connected to the project's workspace. A workspace is connected to an installation in two ways:
Install from an org-bound link. Pass orgId when asking for the install link. You must be an admin or owner of that organization. Otherwise the request returns 403 forbidden, or 404 if the organization does not exist:
GET /v1/github/installations?orgId=… accepts the same parameter for the installUrl it returns. Completing the install on GitHub then connects the installation to that organization. Without orgId the link still works, but the installation is only claimed for your own account.
PATCH /v1/projects/{projectId} with a githubInstallationId that you can access on GitHub connects that installation to the project's workspace — see Update Project.Pages, the web editor, the editor agent and the hosted MCP connector only use an installation that the project's workspace is connected to. Anything else returns 403 installation_not_owned (the MCP connector returns a "reconnect the repository" message). Builds follow the same rule: the build clones the repository only through an installation connected to the project's workspace. Otherwise the build fails with "This project's GitHub App installation isn't connected to your workspace. Reconnect the repository in Settings › Repository." Most existing repository connections were carried over automatically. If you see installation_not_owned, have an admin reconnect the repository from the dashboard's repository picker.
Which endpoints accept an API key
API keys are accepted on the automation surface — the build and deploy paths, and the content of projects written in Syntext:
| Endpoint | Method | Scope needed |
|---|---|---|
/v1/projects/:projectId/builds | POST | build |
/v1/projects/:projectId/builds | GET | read |
/v1/projects/:projectId/builds/:buildId | GET | read |
/v1/projects/:projectId/builds/:buildId/cancel | POST | build |
/v1/projects/:projectId/builds/:buildId/logs | GET | read |
/v1/projects/:projectId/builds/:buildId/logs/stream | GET | read |
/v1/projects/:projectId/builds/:buildId/export | GET | read |
/v1/projects/:projectId/versions/diff | GET | read |
/v1/projects/:projectId/deploy | POST | build |
/v1/projects/:projectId/deploy/promote | POST | build |
/v1/projects/:projectId/deploy/rollback | POST | build |
/v1/projects/:projectId/content, /content/files, /content/history, /content/revisions/:number | GET | read |
/v1/projects/:projectId/content/publish | POST | build |
/v1/projects/:projectId/content/revisions/:number/restore | POST | full |
/v1/projects/:projectId/content/import | POST | full |
Everything else — authentication, billing, organization and member management, and API key management itself — requires a session JWT and rejects an API key with 401. This is deliberate: a key is a deployment credential, not an account credential, so it can never escalate into changing billing or issuing further keys.
Sessions
Every session JWT belongs to a session — one sign-in on one browser, or one stx login. You can see and sign out your sessions from the dashboard, or with the sessions endpoints.
| Session | How it starts | Tokens |
|---|---|---|
| Browser | Signing in with email and password, or with GitHub | A 1-hour access token and a 30-day refresh token. Each refresh issues a new pair for the same session; a refresh token works once. |
stx CLI | stx login in the terminal, approved in the browser | One token valid for a year, with no refresh |
Access tokens carry the session id as the sid claim — the same id that List Sessions returns. A session records the user agent and IP address it started from, so you can tell sessions apart. They are for display only and never used for access decisions.
Signing sessions out
On every request Syntext checks that the token's session is still live — including tokens passed as ?token= to the build log stream and to the GitHub account-linking redirect. Once a session is signed out, any request made with its token fails straight away, even if the token itself hasn't expired:
The status is 401. Treat it like any other 401: clear the stored token and sign in again.
These actions sign sessions out:
| Action | Signs out |
|---|---|
POST /v1/auth/logout | Every session, including the current one |
Resetting your password with a reset link (POST /v1/auth/reset-password) | Every session |
| Change Password | Every session except the current one |
| Revoke Other Sessions | Every session except the current one |
| Revoke Session | That one session |
| Delete Account | Every session |
"Every session" covers browsers and stx CLI logins alike. stx CLI tokens issued before sessions were introduced don't appear in the session list. They are signed out by every action in the table except revoking a single session.
Revocation and expiry
A key stops working immediately when it is deleted, and automatically once its expiresAt passes. In both cases requests return 401 Unauthorized.
Rotating a key revokes it and issues a replacement with a new id and the same name, scope and expiry; previousKeyId in the response names the old one:
Delete a key outright:
List keys for a project (secrets are never returned):
Errors
| Status | Meaning |
|---|---|
| 401 | Missing credential, malformed or expired JWT, a JWT whose session has been signed out (session_revoked — see Sessions), or an unknown, revoked, or expired API key |
| 403 | Valid credential, but the key's scope is too low, the user is not a member of the owning organization, or the user's role is too low for the action — or, for a change, the account (or the key's creator) hasn't verified its email (email_not_verified — see Email verification) |
| 404 | The project does not exist, or the key is scoped to a different project |
A cross-project request returns 404 rather than 403 so that project existence is not disclosed to a key that has no business knowing about it.
Environment variables
Store keys in environment variables, never in source:
Never expose API keys in client-side code, public repositories, or logs. Syntext never logs the key or its hash.
Security best practices
read for dashboards, build for CI.expiresInDays so forgotten keys age out.lastUsedAt in the key list for anomalies.