API Authentication

The public API authenticates with the OAuth 2.0 client credentials grant: your server exchanges a client_id and client_secret for a short-lived access token. There is no browser redirect and no user interaction — the token acts on behalf of your whole workspace account.

1. Create an API app

In the web app, open Settings → Developer (paid plans only) and create an API app:

1. Enter a name (for example invoice-importer) and click Create App.
2. Copy the client secret immediately — it is shown only once and stored hashed. The client ID stays visible in the list.

Treat the secret like a password. If it leaks, use Rotate Secret to invalidate it and get a new one.

2. Request an access token

POST https://app.docstosheets.com/connect/token with form-encoded credentials:

curl -X POST https://app.docstosheets.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=dts_app_YOUR_CLIENT_ID" \
  -d "client_secret=dts_secret_YOUR_CLIENT_SECRET" \
  -d "scope=api.read api.write"

Response:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

If scope is omitted, both api.read and api.write are granted. API apps can also request mcp.read and mcp.write explicitly to call the MCP server with the same token mechanism. Requesting any other scope is rejected.

3. Call the API

Send the token in the Authorization header:

curl https://app.docstosheets.com/api/mailboxes \
  -H "Authorization: Bearer eyJhbGciOi..."

Token lifetime

Access tokens expire after about one hour (expires_in is authoritative). The client credentials grant does not issue refresh tokens — simply request a new token when the old one expires. Cache the token and reuse it until shortly before expiry rather than requesting a new one per call.

Revocation and rotation

• Rotate Secret (Settings → Developer) invalidates the current secret immediately; new tokens require the new secret.
• Delete removes the app; no new tokens can be issued for it.
• In both cases, access tokens that were already issued remain valid until they expire (at most ~1 hour).
• If your subscription lapses, token requests are refused until the plan is active again.

Errors

Error	Meaning
invalid_client	Unknown client ID or wrong secret
unauthorized_client	The account has no active paid plan, or the client cannot use this grant
invalid_scope	A scope other than api.read / api.write / mcp.read / mcp.write was requested