> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dust.tt/llms.txt
> Use this file to discover all available pages before exploring further.

# API scopes and permissions

> Which calls need an Admin API key, write access to a Space or Pod, or a signed-in user.

You can call the Dust API in two ways:

* **With an API key.** The key acts on its own, not as a person. What it can do depends on its access scope and on the Spaces and Pods added to it. Admins create keys in **Admin > Developers**: see [API keys](https://docs.dust.tt/docs/user-documentation/admins/api-keys.md).
* **As a signed-in user**, for example after `dust login` in the [Dust CLI](https://docs.dust.tt/docs/developer-platform/dust-cli/dust-cli.md). The request can do what that person can do in Dust, based on their [role and permissions](https://docs.dust.tt/docs/user-documentation/admins/admin-governance/workspace-governance-roles-groups-and-permissions.md).

Most calls work with any API key. This page lists the ones that don't.

## API key scopes

| Scope | What the key can do |
| - | - |
| **Read-only** | Create conversations, post messages, and read agents, skills, and data sources. It can read what every workspace member can read, and write in the Spaces and Pods added to it. |
| **Admin** | Everything a Read-only key can do, plus the calls in [Calls that need the Admin scope](#calls-that-need-the-admin-scope). |

Older keys can show the **Read & write** scope, which you can't choose for new keys.

## Calls that need the Admin scope

With another scope, these calls return `403`. Unless the details say otherwise, a signed-in user needs the **Admin** role.

| Call | Details |
| - | - |
| [Update agent configuration](https://docs.dust.tt/api-reference/agents/update-agent-configuration.md) | Applies to every field. `userFavorite` also needs a signed-in user. |
| [Archive agent configuration](https://docs.dust.tt/api-reference/agents/archive-agent-configuration.md) | |
| [Get agent configuration](https://docs.dust.tt/api-reference/agents/get-agent-configuration.md) | Needed for unpublished agents, and for agents the key can't read otherwise. |
| [List agents](https://docs.dust.tt/api-reference/agents/list-agents.md) | Only with `view=all_unrestricted`. |
| [Import agent configuration](https://docs.dust.tt/api-reference/agents/import-agent-configuration.md) | Other keys can import when **Create agents** is set to **Everyone** in **Admin > Governance**, the default. A signed-in user needs the **Create agents** permission. |
| [Export workspace analytics](https://docs.dust.tt/api-reference/analytics/export-workspace-analytics.md) | Managers can view Analytics in Dust, but this export needs the Admin scope or role. |
| [Export consumption analytics](https://docs.dust.tt/api-reference/analytics/export-consumption-analytics.md) | Other keys need groups under **Analytics**, and the export only covers those groups. Only works with an API key: signed-in users get `403`. |
| [List triggers](https://docs.dust.tt/api-reference/triggers/list-triggers.md), [Get a trigger](https://docs.dust.tt/api-reference/triggers/get-a-trigger.md) | |
| [List skills](https://docs.dust.tt/api-reference/skills/list-skills.md) | Only with `bypassEditorVisibility=true`. |
| [Archive a skill](https://docs.dust.tt/api-reference/skills/archive-a-skill.md) | A signed-in user can also archive a skill they edit. |
| [Update a data source view](https://docs.dust.tt/api-reference/datasourceviews/update-a-data-source-view.md) | |
| [Delete a table](https://docs.dust.tt/api-reference/datasources/delete-a-table.md) | Older **Read & write** keys also work. |

## Calls that write to a Space or a Pod

These calls need write access to the Space or the Pod. Add it under **Spaces and Pods** when you create the key.

* Upsert or delete documents, tables, and table rows in a folder, for example [Upsert a document in a data source](https://docs.dust.tt/api-reference/datasources/upsert-a-document-in-a-data-source.md), [Upsert a table](https://docs.dust.tt/api-reference/datasources/upsert-a-table.md), or [Upsert rows](https://docs.dust.tt/api-reference/datasources/upsert-rows.md).
* [Upload a file into a Pod](https://docs.dust.tt/api-reference/spaces/upload-a-file-into-a-pod.md), and list the files already in it.

You can't write to a [connection](https://docs.dust.tt/docs/user-documentation/data-sources/connections.md) through the API: Dust syncs its content from the source.

## Calls that need a signed-in user

API keys can't make these calls, whatever their scope. They return `400`, `401`, or `403`.

* [Get feedbacks for a conversation](https://docs.dust.tt/api-reference/feedbacks/get-feedbacks-for-a-conversation.md), [Submit feedback](https://docs.dust.tt/api-reference/feedbacks/submit-feedback-for-a-specific-message-in-a-conversation.md), and [Delete feedback](https://docs.dust.tt/api-reference/feedbacks/delete-feedback-for-a-specific-message.md).
* [List agents](https://docs.dust.tt/api-reference/agents/list-agents.md) with `view=list` or `view=favorites`.
* [Update agent configuration](https://docs.dust.tt/api-reference/agents/update-agent-configuration.md) with `userFavorite`.
* [Create a new conversation](https://docs.dust.tt/api-reference/conversations/create-a-new-conversation.md) or [Create a message](https://docs.dust.tt/api-reference/conversations/create-a-message.md) with `clientSideMCPServerIds` or `selectedMCPServerViewIds` in the message context.
* [Register a client-side MCP server](https://docs.dust.tt/api-reference/mcp/register-a-client-side-mcp-server.md).

## Conversations

Which conversations a key can open depends on who they're shared with. See [Conversation sharing](https://docs.dust.tt/docs/developer-platform/core-concepts/conversation-sharing.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.