> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/introduction/api-token-security.md).

# API token security

This document explains how to store, use, and replace DocStudio API tokens securely.

{% hint style="info" %}
API tokens provide access to DocStudio API, so they must be stored and used carefully. Treat every token as a secret value.
{% endhint %}

### Scope

These security rules apply to any token used with DocStudio API, including:

* application tokens
* authorization tokens returned by the /api/login endpoint

Application tokens are usually used by integrations, backend services, automation scripts, and server-to-server workflows. Authorization tokens returned by /api/login are temporary and expire after 3 hours, but they must still be protected while they are valid.

### Store tokens securely

Store API tokens only in secure server-side storage. Do not hardcode tokens directly in source code or configuration files that can be shared, copied, or committed to a repository.

Use secure storage such as:

{% columns %}
{% column %}

* environment variables on a protected server
* encrypted CI/CD variables
* secret managers
  {% endcolumn %}

{% column %}

* protected backend configuration
* secure infrastructure-level secrets storage
  {% endcolumn %}
  {% endcolumns %}

Example environment variable:

```dotenv
DOCSTUDIO_API_TOKEN={token}
```

The exact storage method depends on your infrastructure, but the rule is the same: the token must be available only to the trusted backend service that sends API requests to DocStudio.

### Use tokens only on the server side

Do not use DocStudio API tokens in client-side code, public frontend applications, mobile applications, or static websites. Users, browser tools, proxies, and other software can inspect client-side code. Treat every token stored there as exposed.

Do not put tokens in:

{% columns %}
{% column %}

* JavaScript frontend code
* mobile application code
* browser local storage
* browser session storage
  {% endcolumn %}

{% column %}

* cookies available to client-side scripts
* public configuration files
* static website assets
* frontend environment variables included in a public build
  {% endcolumn %}
  {% endcolumns %}

If a frontend or mobile application needs to start a DocStudio API action, send the request to your backend first. The backend should add the DocStudio API token and call DocStudio API from a protected server-side environment.

### Do not expose tokens

Never share tokens in places where other users, systems, or third-party tools can access them.

Do not include tokens in:

{% columns %}
{% column %}

* public repositories
* private repositories with broad access
* screenshots
* screen recordings
* logs
* error messages
* browser console output
  {% endcolumn %}

{% column %}

* support tickets
* chat messages
* shared documents
* test reports
* API examples in documentation
* monitoring tools without secret masking
  {% endcolumn %}
  {% endcolumns %}

When you write examples, always replace real tokens with placeholders.

Correct example:

```http
Authorization: Bearer {token}
```

### Protect the Authorization header

DocStudio API tokens are sent in the Authorization header.

```http
Authorization: Bearer {token}
```

Make sure your application does not print this header in logs, error traces, analytics events, or monitoring tools. If request logging is enabled, mask the Authorization header before the request is stored.

Recommended masked format:

```http
Authorization: Bearer ***
```

### Use separate tokens for separate integrations

Do not reuse the same token for every system, environment, or integration. Separate tokens make it easier to control access and replace only the affected token if something goes wrong.

Use separate tokens for:

{% columns %}
{% column %}

* production environments
* staging or testing environments
* different backend services
  {% endcolumn %}

{% column %}

* different automation jobs
* different external integrations
  {% endcolumn %}
  {% endcolumns %}

For example, do not use the same token for a production CRM integration and a local developer test script. If the test script exposes the token, the production integration should not be affected.

### Use the minimum required access

Create and use tokens from a user or account context that has only the access required by the integration. If an integration only needs to send envelopes from a specific mailbox, do not use a token connected to a user with unnecessary access to unrelated mailboxes or account settings.

Authentication proves who sends the request, but endpoint permissions still define what the token can access. A valid token can still receive a 403 Forbidden response if the token owner does not have access to the requested mailbox, envelope, template, account, domain, dictionary, or other resource.

### Replace tokens when needed

Replace tokens regularly according to your internal security policy. You should also replace a token immediately if there is any chance that it was exposed.

Rotate a token when:

{% columns %}
{% column %}

* a developer with token access leaves the project
* a token was shared in a chat, ticket, screenshot, or document
* a token was committed to a repository
* a token appeared in logs or monitoring tools
  {% endcolumn %}

{% column %}

* a token was used on an unsafe device
* an integration is moved to a new environment
* your internal security policy requires scheduled rotation
  {% endcolumn %}
  {% endcolumns %}

To replace a token, create a new token, update the integration, test the new token, and stop using the old token.

### Respond to an exposed token

If a token is exposed, treat it as compromised even if you do not see suspicious activity.

{% hint style="danger" %}
Replace an exposed token immediately. Do not wait for suspicious activity or an integration failure.
{% endhint %}

1. Stop using the exposed token.
2. Create a new token in DocStudio.
3. Update the integration to use the new token.
4. Test the integration with the new token.
5. Remove the exposed value from repositories, logs, tickets, screenshots, documents, or other unsafe places.
6. Check whether any unexpected API activity happened while the token was exposed.

### Local development

For local development, store tokens in a local environment file that is not committed to the repository.

For example, use a local .env file:

```dotenv
DOCSTUDIO_API_TOKEN={token}
```

Add local environment files to .gitignore before adding token values.

Example .gitignore entry:

```gitignore
.env
.env.local
```

Do not send local environment files to other people. If another developer needs access, they should create or receive their own token through the approved process.

### CI/CD and automation

For CI/CD pipelines and automation jobs, store tokens as protected secret variables. Do not write tokens directly in pipeline files, deployment scripts, Dockerfiles, or build logs.

Make sure that:

* secret variables are available only to the required jobs
* secret values are masked in logs
* pull requests from untrusted branches cannot print secrets
* deployment logs do not expose request headers
* failed jobs do not print full API request configuration

### Common mistakes

Avoid these common token security mistakes:

{% columns %}
{% column %}

* hardcoding tokens in source code
* committing .env files to a repository
* using production tokens in local test scripts
* sharing one token across all integrations
* sending tokens in chat messages or support tickets
  {% endcolumn %}

{% column %}

* recording videos with visible tokens
* logging the full Authorization header
* storing tokens in browser local storage
* using tokens directly in frontend code
* forgetting to replace exposed tokens
  {% endcolumn %}
  {% endcolumns %}

### Security checklist

Before using a token in an integration, check that:

{% columns %}
{% column %}

* The token is stored in secure server-side storage.
* The token is not hardcoded in source code.
* The token is not available in frontend or mobile code.
  {% endcolumn %}

{% column %}

* The Authorization header is masked in logs.
* The token is not included in screenshots, tickets, or shared documents.
* The token belongs to the correct user or account.
  {% endcolumn %}

{% column %}

* The token owner has only the access required by the integration.
* Production and test environments use separate tokens.
* There is a process for replacing exposed tokens.
  {% endcolumn %}
  {% endcolumns %}

### Related topics

* [Authentication and application tokens](/introduction/authentication-and-application-tokens.md)
* [Send your first envelope](/introduction/send-your-first-envelope.md)
* [Authorization](/api-reference/authorization.md)
* [Error handling and API error codes](/error-codes/error-handling-and-api-error-codes.md)