From de9422bbd67b456c3e205be2da21b6eff4363280 Mon Sep 17 00:00:00 2001 From: Yacine Kahlerras Date: Tue, 18 Aug 2026 16:07:13 +0100 Subject: [PATCH] docs(api): recommend API keys over user access tokens The Authentication section still said "TurboDocx is working on it's API Key flows, and for the time being, we recommend grabbing the access token used from your user's accounts". API keys have shipped and are what every SDK guide already uses, so the page was steering integrators onto the fragile path: a user access token is tied to a signed-in session and expires, which breaks unattended backend jobs. Document both credentials, say plainly which one to reach for, and add the same distinction to the SDK "Get Your Credentials" section that the other SDK pages link to. Co-Authored-By: Claude Opus 5 --- docs/API/turbodocx-api-documentation.info.mdx | 17 ++++++++++++++--- docs/SDKs/index.md | 9 +++++++++ 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/API/turbodocx-api-documentation.info.mdx b/docs/API/turbodocx-api-documentation.info.mdx index 47833cec..b5ba2e82 100644 --- a/docs/API/turbodocx-api-documentation.info.mdx +++ b/docs/API/turbodocx-api-documentation.info.mdx @@ -40,18 +40,29 @@ https://api.turbodocx.com ## Authentication -TurboDocx is working on it's API Key flows, and for the time being, we recommend grabbing the access token used from your user's accounts to leverage our APIs. You can find an example on how to get your access token in the `Blueprint` folder. +Every request is authenticated with a bearer credential in the `Authorization` header. There are two kinds, and for server-to-server integrations you want the first one. -To use the Access Token, use the following under the `Authorization Header` +**API key (recommended).** A long-lived key you generate in your organization settings. It belongs to the organization rather than to a browser session, so it does not expire when someone logs out and it is the credential every TurboDocx SDK uses by default. See [Get Your Credentials](/docs/SDKs#1-get-your-credentials). + +``` typescript +Authorization: Bearer YOUR_API_KEY + + ``` + +**User access token (alternative).** A short-lived OAuth token issued by TurboDocx's identity provider when a user signs in. It is scoped to that user's session, so it expires and must be refreshed — which makes it a poor fit for unattended backend jobs. Prefer an API key unless you are acting on behalf of a signed-in user. ``` typescript Authorization: Bearer YOUR_ACCESS_TOKEN ``` +:::tip Which one should I use? +If your code runs on a server without a person present, use an **API key**. Reach for a user access token only when the request genuinely has to act as a specific signed-in user. +::: + ### Authentication error response -If an Access Token is missing, malformed, or invalid, you will receive an HTTP 401 Unauthorized response code. +If the credential is missing, malformed, expired, or invalid, you will receive an HTTP 401 Unauthorized response code. ### **Need some help?** diff --git a/docs/SDKs/index.md b/docs/SDKs/index.md index cbc208ba..df83289a 100644 --- a/docs/SDKs/index.md +++ b/docs/SDKs/index.md @@ -133,6 +133,15 @@ TurboSign also requires a `senderEmail` (used as the reply-to address for signat 3. **API Keys Section**: Generate or copy your API access token 4. **Organization ID**: Copy your organization ID from the same settings page +:::note `apiKey` vs `accessToken` +Some SDKs accept an `accessToken` as an alternative to `apiKey` (when both are set, `accessToken` wins). They are not interchangeable in practice: + +- **`apiKey`** — a long-lived organization credential from the settings page above. It does not expire with a browser session, so it is the right choice for servers, scheduled jobs, and every example in these guides. +- **`accessToken`** — a short-lived OAuth token issued by TurboDocx's identity provider when a user signs in. It is tied to that user's session and must be refreshed when it expires. + +Use `apiKey` unless your integration specifically has to act as a signed-in user. +::: + ![TurboSign API Key](/img/turbosign/api/api-key.png) ![TurboSign Organization ID](/img/turbosign/api/org-id.png)