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

# Data sources

> Let components on your canvases read from and write to a service you approve, without exposing its secrets to the agent or to viewers.

A data source is a service, such as your own API, that components on your canvases may call. Components never reach the network themselves. CanvasView calls the source for them, adds the secret headers you entered, and returns the answer to the component.

Admins create and manage data sources. An agent can list them and ask for a new one, but it cannot create one, change one or read its secrets.

Members see each source's name, host and methods on the Data sources page, and are asked to contact an Admin to add or change one. Data sources belong to the organization, so any member's canvases can use them.

## Add a data source

1. Open [Data sources](https://app.canvasview.dev/settings/data-sources).
2. Under **Add a source**, enter a **Name**, such as `orders`. Agents and components use this name. It is 2 to 64 lowercase letters, digits and hyphens, starting with a letter, and cannot be changed later.
3. Enter the **Base URL**, such as `https://api.example.com/v1`. It must use HTTPS on a public host, with no query.
4. Optionally enter a **Path prefix**, such as `/orders`. Components can then only call paths under the base URL and this prefix.
5. Choose the **Allowed methods**. Only GET is selected by default. POST, PUT, PATCH and DELETE let components write.
6. Under **Secret headers**, select **Add header** for each credential the service needs, such as `Authorization`. You can add up to 5.
7. Select **Add source**.

An account can hold up to 20 data sources.

## Use a limited key

> [!WARNING]
>
> Anyone who can open a canvas that uses a source can make it request any path under its base URL and prefix, with any method you allowed. Give each source a key that can do only what those canvases need. Never use an admin or service key.

* Set a path prefix that covers only what the canvas needs.
* Allow write methods only when a component must write. Writes work on active canvases only.
* Add only services you trust. A service that repeats request headers in its answers would show a secret to viewers.

## What each party can see

| | Can see | Cannot see |
| - | - | - |
| Admins | Each source's name, base URL, prefix, methods and header names | Header values after they are saved |
| Members | Each source's name, host and methods | Everything else |
| The agent | Each source's name, host, prefix, methods and header names | Header values |
| A component | The status, content type and body of each answer | Header values, and any response header other than the content type |
| The service | The request path, query, body, and the content type and accept headers the component sets | The viewer's cookies, sign-in, IP address or identity |

The service sees the viewer's email only if an Admin turns on **Send the viewer's verified email as X-CanvasView-Viewer on canvases that need sign-in**. CanvasView then adds the header on canvases that use sign-in or invitations. It never sends it on link-access canvases.

Secret header values are stored encrypted. CanvasView never shows a value again. To change a value, select **Edit**, enter a new value and select **Save source**. Leave a stored value empty to keep it.

## How a canvas uses a source

A canvas can call a source only when its agent lists the source's name in the canvas's `dataSources`. The canvas then shows viewers which of your sources its components load data from.

A canvas that uses a source needs sign-in by default, because anyone who can open it can call the source. See [Sharing and access](https://docs.canvasview.dev/account/sharing-and-access.md#canvases-that-use-a-data-source).

CanvasView refuses a call when:

* the canvas does not declare the source, or the method is not allowed;
* the path leaves the base URL and prefix;
* a viewer makes more than 60 requests a minute, or a canvas more than 600;
* the request body is larger than 256 KB, or the answer larger than 1 MB;
* the source does not answer within 10 seconds, redirects, or answers with something other than JSON or text.

## Requests from agents

When an agent needs a source you do not have, it can ask for one with a name, a base URL and a reason. The request appears under **Requested by agents** on an Admin's Data sources page, and as an action in your organization's [notifications](https://docs.canvasview.dev/account/notifications.md).

Check the address and reason first. An agent asked for it, not a person.

* To approve it, set up a source with the requested name. This answers the request.
* To decline it, select **Dismiss**.

## Remove a data source

An Admin selects **Remove** next to the source. Before confirming, CanvasView lists the live canvases that still declare it. Their components stop reaching the source at once. The organization gets a notification naming those canvases. It clears itself when no live canvas declares the source any more, or when you add the source again.

## Developers

Components call a source with `useData` or `fetchData` from `@canvasview/kit`. See [Custom components](https://docs.canvasview.dev/developers/custom-components.md#live-data).


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