Docs Access

Authentication

Two ways in: sign in from an AI app, or send an API key. Both are for owners and admins.

Every request to the endpoint carries a credential in the Authorization header. There are two kinds. Both act for the person who created them, inside one workspace, within the scopes they chose.

Sign-in (OAuth)API key
Made forChat apps: ChatGPT, Claude, Gemini, Grok, PerplexityEditors, command-line tools and your own code
How it startsThe app sends you to Soontra to sign in and approveYou create a key in Settings and paste it into the tool
How manyOne connection per personUp to 25 active keys per workspace
AccessAn access level, plus optional boxesA switch per scope
Ends whenYou disconnect it, or connect another appIt expires, or you revoke or rotate it

Sign in from an AI app

Give the app the endpoint URL. On its first request the server answers 401 and points the app to Soontra’s sign-in, following the MCP authorization spec, so an app that supports remote MCP servers needs nothing else from you.

  1. The app opens Soontra in your browser. Sign in if you are not already.

  2. Choose the workspace to connect.

  3. Choose an access level.

    Full access (recommended): read the workspace and file content, see analytics, and create or edit drafts, projects and documents. Content access: the same, without creating or changing anything. Read-only: names and structure only.

  4. Open Advanced options to change individual scopes.

    Download files is not part of any access level. Tick it if the app should show previews, play media or make download links.

  5. Choose Authorize.

One connection per person

Each person has one signed-in connection at a time, to one workspace. Signing in from a second app, or to a second workspace, replaces the earlier connection. The earlier app then gets 401 with a message asking you to reconnect. API keys are separate and are not affected.

For client developers

  • An unauthenticated request gets 401 with WWW-Authenticate: Bearer realm="soontra-mcp", a resource_metadata URL and scope="offline_access".
  • The protected resource metadata (RFC 9728) is at https://app.soontra.com/.well-known/oauth-protected-resource/api/mcp. It names the authorization server, which publishes its own metadata and supports dynamic client registration.
  • Request offline_access to receive a refresh token.
  • The scopes a connection has are the ones approved on Soontra’s screen, not the ones in the token request.

API keys

  1. In Soontra, open Settings, then API & MCP, and switch to API.

  2. Choose Create New.

  3. Name the key and set what it may do.

    A name (up to 80 characters), an optional expiry date, a switch for each scope (read is always on), and an optional list of up to 20 IP addresses or CIDR blocks the key may be used from.

  4. Copy the key.

    It is shown once. Soontra stores only a hash, so a lost key cannot be recovered: create another.

Sending a key

HTTP
Authorization: Bearer soontra_sk_live_...
  • Keys start with soontra_sk_live_.
  • Send the key in the header only. A key in a query string is refused.
  • Treat a key like a password: keep it out of chats, shared config files and version control.

Rotating and revoking

  • Rotate makes a new key with the same name and scopes and revokes the old one. The new key is shown once.
  • Revoke stops a key at once and cannot be undone.
  • The workspace owner can revoke every key at once.
  • A workspace can hold 25 active keys. Revoke one to make room for another.

When authentication fails

A missing, wrong, expired or revoked credential always gets the same 401, so a caller cannot tell which it was. See Errors.