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)