> For the complete documentation index, see [llms.txt](https://docs.distro.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.distro.so/developers/authentication.md).

# API authentication and workspaces

Call the Distro API from a trusted server using an API token for the acting member.

## Create a token

Open **API tokens** in your account settings, give the token a clear name and choose the access scopes you need. Copy the secret when it is created; later list views do not reveal it again.

Keep it in your server's secret storage. Send it as:

```http
Authorization: Bearer YOUR_DISTRO_API_TOKEN
Content-Type: application/json
```

Use your Distro application URL as the base URL. Paths in these guides are relative to that URL.

## Choose scopes

| Operation                                           | Permission                                          |
| --------------------------------------------------- | --------------------------------------------------- |
| List API-triggered workflows                        | `visual_workflows:read` or `visual_workflows:start` |
| Start a workflow and read a run started by that key | `visual_workflows:start`                            |
| Read event/link details and availability            | `scheduling_links:read`                             |
| Create an event link                                | `scheduling_links:write`                            |
| Book or issue a scheduling artifact                 | `scheduling_links:write`                            |
| Look up a lead                                      | `records:read` or `records:enrich`                  |
| Read enrichment options or run a lookup             | `records:enrich`                                    |
| Read bookings or open reschedule times              | `bookings:read`                                     |
| Move, cancel or change no-show state                | `bookings:write`                                    |

A full-access token can satisfy these permissions. Token scopes do not override membership, resource permissions or feature availability.

## Select a workspace

Workflow trigger and run requests require an explicit `account_id` query parameter. Scheduling-link routes include `account_id` in the path.

The acting member must belong to that workspace, and the token must allow it. Scoped tokens created in a workspace are restricted to that workspace. An omitted or inaccessible workspace does not silently select another one.

Bookings use the acting member's permitted resources and token workspace restrictions.

Delete a token when retiring its integration. See [API errors and retries](/developers/errors.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.distro.so/developers/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.