/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API API Reference Authentication

Authentication

Authenticate with the Syntext API using a session JWT or a project-scoped API key.

10 min read

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:

CallerCredentialUse it for
A person in the dashboardSession JWTInteractive use — the dashboard handles this for you
A person using the stx CLISession JWT from stx loginRunning CLI commands as yourself
A machine, script, or CI jobProject API key (stx_...)Automated builds and deploys

Both are presented in the same header, so most clients need no special handling:

text
Authorization: Bearer <token>

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:

•
A key issued for project A cannot read or modify project B. Requests that try return 404 Not Found — Syntext does not confirm whether the other project exists.
•
Revoking a key affects only that one project.

If you automate several projects, create one key per project.

Note

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:

ScopeCan do
readRead builds, build logs, export bundles and version diffs, plus hosted content status, files, history and revisions, and imported OpenAPI specs and endpoints
buildEverything in read, plus trigger and cancel builds, deploy, promote and roll back deployments, publish hosted content, and import or remove OpenAPI specs
fullEverything 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:

bash
curl -X POST https://api.syntext.dev/v1/projects/$PROJECT_ID/api-keys \
-H "Authorization: Bearer $SYNTEXT_JWT" \
-H "Content-Type: application/json" \
-d '{ "name": "CI deploy", "scope": "build", "expiresInDays": 90 }'
json
{
"data": {
"id": "key_def456",
"name": "CI deploy",
"key": "stx_A1b2C3d4_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"prefix": "stx_A1b2C3d4",
"last4": "xxxx",
"scope": "build",
"expiresAt": "2025-04-21T10:00:00Z",
"createdAt": "2025-01-21T10:00:00Z"
}
}
Note

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

text
stx_A1b2C3d4_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
└──────┬────┘
the first 12 characters are the key's prefix

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:

bash
curl -X POST https://api.syntext.dev/v1/projects/$PROJECT_ID/builds \
-H "Authorization: Bearer $SYNTEXT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "branch": "main" }'

An X-API-Key header is also accepted, if that suits your client better:

bash
curl -X POST https://api.syntext.dev/v1/projects/$PROJECT_ID/builds \
-H "X-API-Key: $SYNTEXT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "branch": "main" }'

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:

•
API key: the key is bound to one project, so a key for project A used against project B returns 404 Not Found.
•
Session JWT: your org memberships are checked against the project's owning org. A project that does not exist (or is deleted) returns 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.
Note

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 surfaceEndpoints
Analytics beaconsPOST /analytics/pageview, /analytics/search, /analytics/chat, /analytics/playground, /analytics/funnel
Site searchGET /search, GET /search/popular
AI assistantthe chat endpoints
Community widgetspage 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:

1.

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:

bash
curl "https://api.syntext.dev/v1/github/install-url?orgId=$ORG_ID" \
-H "Authorization: Bearer $SYNTEXT_JWT"

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.

2.
Set it on a project. 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:

EndpointMethodScope needed
/v1/projects/:projectId/buildsPOSTbuild
/v1/projects/:projectId/buildsGETread
/v1/projects/:projectId/builds/:buildIdGETread
/v1/projects/:projectId/builds/:buildId/cancelPOSTbuild
/v1/projects/:projectId/builds/:buildId/logsGETread
/v1/projects/:projectId/builds/:buildId/logs/streamGETread
/v1/projects/:projectId/builds/:buildId/exportGETread
/v1/projects/:projectId/versions/diffGETread
/v1/projects/:projectId/deployPOSTbuild
/v1/projects/:projectId/deploy/promotePOSTbuild
/v1/projects/:projectId/deploy/rollbackPOSTbuild
/v1/projects/:projectId/content, /content/files, /content/history, /content/revisions/:numberGETread
/v1/projects/:projectId/content/publishPOSTbuild
/v1/projects/:projectId/content/revisions/:number/restorePOSTfull
/v1/projects/:projectId/content/importPOSTfull

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.

SessionHow it startsTokens
BrowserSigning in with email and password, or with GitHubA 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 CLIstx login in the terminal, approved in the browserOne 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:

json
{
"error": {
"code": "session_revoked",
"message": "This session has been signed out. Sign in again.",
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

The status is 401. Treat it like any other 401: clear the stored token and sign in again.

These actions sign sessions out:

ActionSigns out
POST /v1/auth/logoutEvery session, including the current one
Resetting your password with a reset link (POST /v1/auth/reset-password)Every session
Change PasswordEvery session except the current one
Revoke Other SessionsEvery session except the current one
Revoke SessionThat one session
Delete AccountEvery 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:

bash
curl -X POST https://api.syntext.dev/v1/projects/$PROJECT_ID/api-keys/$KEY_ID/rotate \
-H "Authorization: Bearer $SYNTEXT_JWT"

Delete a key outright:

bash
curl -X DELETE https://api.syntext.dev/v1/projects/$PROJECT_ID/api-keys/$KEY_ID \
-H "Authorization: Bearer $SYNTEXT_JWT"

List keys for a project (secrets are never returned):

bash
curl https://api.syntext.dev/v1/projects/$PROJECT_ID/api-keys \
-H "Authorization: Bearer $SYNTEXT_JWT"

Errors

StatusMeaning
401Missing 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
403Valid 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)
404The 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:

bash
export SYNTEXT_API_KEY=stx_A1b2C3d4_...
Warning

Never expose API keys in client-side code, public repositories, or logs. Syntext never logs the key or its hash.

Security best practices

1.
One key per project per system — a key cannot reach across projects, so keep them separate and revoke narrowly.
2.
Use the narrowest scope — read for dashboards, build for CI.
3.
Set an expiry — pass expiresInDays so forgotten keys age out.
4.
Rotate periodically — use the rotate endpoint rather than deleting and recreating.
5.
Monitor usage — check lastUsedAt in the key list for anomalies.
Was this page helpful? Yes No
Previous
Next
Product
Resources
Company
© 2026 SyntextBuilt with Syntext