# Creating and Managing an SDK App

An SDK App is the [Agent Channel](/products/ai-studio/agent-channels/) your own application connects through. Creating one makes a shared work folder reachable from outside Treasure AI Studio, so the wizard asks for two decisions and nothing else: which folder, and on whose authority. This page covers making that decision, storing the credential it produces, and running the channel afterward — pausing it, handing the executor seat over, and shutting it down.

Do this when an application you host needs to start chats: you create the SDK App once, store its token in your server's secret manager, and the application uses it from then on.

## Prerequisites

- A [shared work folder](/products/ai-studio/shared-folders/) that you **manage**. The wizard offers only folders where you hold a work mode with manage rights, and a folder that is archived cannot be chosen.
- Permission to create a channel. Manage access to a shared folder is always required, and the account's creation policy may also require you to be an account administrator. The Agent Channels page shows the policy under **Who can create** — see [Choose Who Can Create Agent Channels](#choose-who-can-create-agent-channels). When it is **Account admins only** and you are not one, **New SDK App** is disabled.
- Treasure AI Studio on **Web or Desktop**, where Agent Channels are created and managed. They cannot be set up from the Mobile app.
- Somewhere to put the token when you get it — a secret manager, not a text file. It is displayed once.


Decide who the executor should be before you start. The creator becomes the executor, and every chat the channel creates will run with that person's permissions, connections, and credits. [What an Agent Channel Chat Can Reach](/products/ai-studio/agent-channels/channel-chats#what-is-not-restricted) explains why that choice, rather than any per-channel setting, is what bounds the channel.

## Create an SDK App

1. Open **Settings → Agent Channels**. The page lists the account's channels under a **SDK Apps** heading. Before the first one is created, the list is replaced by a **Connect your application** guide.


Agent Channels settings page before any SDK App exists: the Who can create row set to All users, the SDK Apps heading with a New SDK App button, and a three-step Connect your application guide
1. Select **New SDK App**. The wizard opens at step 1 of 2 and first checks which shared folders you can use. If you manage none, it says *"Creating an SDK App requires manage access to at least one shared folder. Ask a folder manager to grant you manage access."* instead of showing the form, so you never fill in a name you cannot use.


Step 1 of 2 of the New SDK App wizard showing, in place of the form, a notice that creating an SDK App requires manage access to at least one shared folder
1. Under **Name**, enter a name — for example, *"Campaign assistant for the marketing site"*. Use the application's name, not the folder's — this is what identifies the channel in the ledger and in an audit later. Up to 255 characters.
2. Optionally add a **Comment** for your colleagues, such as the owning team and how to reach them. Up to 1,000 characters. The comment is also where a pause or a handover leaves its note, so treat it as shared rather than permanent.
3. To let browsers call the messaging API directly, expand **Advanced** and select **Allow chats to be driven from end users' browsers**. Leave it off unless your application hands the per-chat token to the browser — with it off, the gateway refuses any call that carries an `Origin` header, so a script running on your page cannot bypass your server. See [Browser access](/products/ai-studio/agent-channels/tokens#browser-access) before turning it on. You can change this later.


Step 1 of 2 of the New SDK App wizard with Name and Comment filled in and Advanced expanded to show the unchecked Allow chats to be driven from end users' browsers option
1. Select **Next**, then choose the **Shared folder** the channel's chats will read. The field searches as you type, and only folders you manage are listed.
2. Read the consent line that appears under the folder. It states what you are authorizing: end users of your application will create chats that read that folder read-only, running under your permissions and cost, with each chat's workspace destroyed when the chat ends. **Executor** is shown as you and cannot be set to someone else here — another manager of the same folder can take the role over later.


Step 2 of 2 of the wizard with a shared folder selected, the executor shown as the current user, the consent text for that folder, and an Expiration of 90 days with its resolved end-of-day date
1. Choose an **expiration** for the first token: **7 days**, **30 days**, **90 days** (the default), a custom date, or **No expiration**. The resolved date is echoed below the field as the end of that day in your personal time zone, which the echo names. Expiration is fixed when a token is issued and cannot be edited afterward; a different expiry means issuing a new token and revoking the old one.
2. Select **Create app & issue first token**. The channel is created and its first Gateway Token is issued in one step, and the completion screen appears.


If the app is created but the token is not
The two actions are separate requests, so the second can fail on its own. When it does, the wizard shows **App created — token pending** rather than starting over: the SDK App exists. Choose **Retry issuing a token**, or **Issue one later from the app page** and issue it from the channel's detail page when you are ready.

## Store the Connection Details

The completion screen is headed **Connect your server** and shows the two values your application needs, formatted as environment variables:

```bash
AGENT_GATEWAY_URL=<your account's Agent Gateway URL>
GATEWAY_TOKEN=tasgwt_<the secret>
```

Connect your server completion screen with the AGENT_GATEWAY_URL and GATEWAY_TOKEN lines and a Copy all button, a warning that the token will not be shown again, a link to the integration guide, the I have stored the values checkbox, and a disabled Done button
This is the only time the token is shown
The secret is never displayed again, and Treasure AI Studio cannot recover it. Copy both values into your server's secret manager before you leave the page. If you lose the token, the recovery is to revoke it and issue a new one — not to look it up.

1. Select **Copy all**, then paste the values into your secret manager.
2. Select **I have stored the values**. The **Done** button stays disabled until you do.
3. Select **Done**.


Leaving the page before checking the box prompts *"You haven't saved this token yet"* and offers **Go back**. Take it unless you really have stored the token.

The gateway URL is your site's own and does not change. If you need it again later, the channel's detail page shows it as **Agent Gateway URL**.

With the values in hand, the next step is code: [Building a Chat App with the Vercel AI SDK](/products/ai-studio/agent-channels/building-an-app).

## Read the Agent Channels Page

The ledger under **Settings → Agent Channels** is where the account's external entry points are reviewed. Each SDK App is one row:

| Column  | What It Tells You  |
|  --- | --- |
| **Name** | The channel's name, with its comment underneath when one is set |
| **Folder** | The single shared work folder this channel's chats read |
| **Executor** | The user whose permissions and credits the chats run with, shown by email. **No executor** in amber means no one holds the role and the channel cannot run |
| **Status** | The channel's current state (below). A disabled channel adds *"Connections are stopped"* |
| **Eye icon** (last column, unlabelled) | Opens the channel's detail page |


Agent Channels ledger listing three SDK Apps on the same shared work folder: one Stopped — needs an executor with No executor in amber, one Active, and one Disabled with Connections are stopped beneath its status
Every member of the account sees every row, because knowing that a channel exists is not itself access. Unless you manage the folder, are the executor, or are an account administrator, the **Folder** and **Executor** cells show only a dash and a lock icon, and hovering over one shows *"Visible only to members with access."*

Agent Channels page as seen by a member who is not an account administrator: Who can create shows Account admins only with no switch, New SDK App is disabled, and the Folder and Executor cells of every row show a dash and a lock icon
The detail page is masked the same way: it shows the name and status, with a notice that the folder, executor, connection settings, and tokens are visible only to members with access.

Masked SDK App detail page showing only the name, the Active status, and a lock notice that the folder, executor, connection settings, and tokens are visible only to members with access
## Choose Who Can Create Agent Channels

The top of the Agent Channels page shows the account's creation policy under **Who can create**: **All users** or **Account admins only**. Every member sees the current value. **All users**, the default, adds no account-level restriction, but manage access to a shared folder is still required either way.

Account administrators also get a switch next to the value. Turning off **Allow all users to create Agent Channels** limits creation to account administrators, and turning it back on reopens it. The change applies only to channels created from then on. Existing channels and their tokens keep working, and issuing a new token on an existing channel is not affected.

Who can create row on the Agent Channels page set to Account admins only, with the switch turned off
## Channel Statuses

| Status  | Meaning  | How to Clear It  |
|  --- | --- | --- |
| **Active** | The channel accepts connections | — |
| **Disabled** | Someone switched the channel off. Every token under it stops authenticating immediately; none of them is revoked | Turn the switch back on |
| **Stopped — needs an executor** | The executor seat is vacant, because the executor resigned. Nothing runs, and the channel cannot be enabled while it is empty. Tokens are retained | A manager of the folder selects **Become executor**, then enables the channel |


A channel also stops accepting connections, without changing status, if the executor loses their work mode on the folder. Permissions are checked on every request, not only when the channel is saved. When a manager deletes the folder itself, its channels are deleted with it — see [Delete a Channel](#delete-a-channel).

## Manage a Channel

Open a channel from the ledger. What you can do there depends on who you are: the **executor** and any **manager of the channel's folder** can edit it, issue and revoke its tokens, and delete it; an **account administrator** can only switch it off and back on; and a folder manager who is not the executor can take the executor role over. Resigning is the executor's alone.

Detail page of an active SDK App: the Enabled switch, the consent summary, Overview with folder, executor and creator, Connection settings with Agent Gateway URL, browser access and the two chat token TTLs, the Tokens table with Issue token, Resign as executor, and Delete app in the danger zone
### Pause and Resume

Use the **Enabled** switch in the header to stop a channel without destroying anything. Turning it off asks for an optional comment — write why, because that note is what tells the next person whether it is safe to turn back on. Every token under the channel stops authenticating at once, and turning the switch back on restores exactly the arrangement that was there before.

This is the right tool for an incident: it is immediate, it is reversible, and it is the only channel action an account administrator can take, deliberately — administrators can contain a problem but cannot make it permanent.

Disable this SDK App? dialog explaining that every token stops authenticating immediately, with an optional comment field and a Disable button
### Edit a Channel's Settings

**Edit** on the detail page changes the channel's name, its comment, whether browser access is allowed, and the two Chat Access Token lifetimes. The folder and the executor are not among them: those are what the channel was consented to on, and changing either would make it a different arrangement.

The lifetimes are entered in seconds, as **Idle TTL (seconds)** and **Maximum TTL (seconds)**. Leave them blank for the defaults — 24 hours idle and 30 days maximum. A value you enter must be a positive whole number of seconds, with the idle value at or below the maximum.

Edit SDK App dialog with Name, Comment, a Browser access checkbox, and empty Idle TTL and Maximum TTL fields in seconds that fall back to 24 hours and 30 days
### Take Over or Step Down as Executor

The executor role carries the consent, so it changes hands only by the two people involved each acting for themselves.

- **To step down**, select **Resign as executor**. The seat empties and the channel is disabled in the same action; existing tokens are kept but stop working. Add a comment so the folder's managers know what happened.
- **To take over**, open the channel and select **Become executor**. You must manage the channel's folder, and you can do this whether or not the channel currently has an executor. Taking the role does not restart a stopped channel — enable it afterward, which is the point at which you are agreeing that its chats run on your permissions and cost.


Detail page header of an SDK App with the status Stopped — needs an executor, the switch off, and a banner offering Become executor, explaining that existing tokens are retained and will run with your permissions and cost once you enable the app
There is no way to appoint someone else. Handover is a claim, not an assignment.

### Issue and Revoke Tokens

The **Tokens** section lists every token ever issued for the channel, active and inactive together, so a rotation reads as the old row beside the new one. Each row shows the token hint, its status, when it was issued and by whom, when it expires, and when it was last used.

The executor and any manager of the channel's folder can issue and revoke. [Gateway Tokens and Chat Access Tokens](/products/ai-studio/agent-channels/tokens) covers rotation and what a revocation stops.

### Delete a Channel

**Delete app**, in the danger zone at the bottom of the detail page, permanently removes the channel, and every token under it stops working for good. You are asked to type the channel's name to confirm. When a manager deletes a shared work folder, every channel on it is deleted the same way.

Deleting does not delete the chats the channel created; those stay in the executor's chat list under the account's normal retention. Prefer disabling when you might want the channel back — deletion cannot be undone, and recreating a channel means a new token and a redeployment of your application.

## Troubleshooting

| Symptom  | Cause and Fix  |
|  --- | --- |
| The wizard shows *"Creating an SDK App requires manage access to at least one shared folder"* instead of the form | You hold no work mode with manage rights on any shared work folder. Ask a manager of the folder you need to grant you one, or ask them to create the channel |
| **New SDK App** is disabled, or the wizard says only account admins can create Agent Channels | **Who can create** is set to **Account admins only** and you are not an account administrator. Ask an account administrator to create the channel, or to allow all users to create |
| The channel shows **Stopped — needs an executor** | The executor resigned. A manager of the folder takes the role with **Become executor**, then enables the channel |
| The **Enabled** switch will not turn on | The executor seat is vacant. A manager of the folder takes the role with **Become executor**, and the switch can then be turned on |
| Your application gets `401` from the gateway on every call | The token is revoked or expired, the channel is disabled, the executor's access to the folder is gone, or the channel or its folder has been deleted. Check the channel's status and its token row first |
| Your application gets `403` with a message about browsers | The call carried an `Origin` header while browser access is off. Either your proxy is forwarding the browser's `Origin` header — it should not — or the browser is calling the gateway directly. See [Browser access](/products/ai-studio/agent-channels/tokens#browser-access) |
| You lost the token | It cannot be recovered. Revoke it and issue a new one |


## Next Steps

- [Gateway Tokens and Chat Access Tokens](/products/ai-studio/agent-channels/tokens) — rotation, revocation, and the per-chat credential.
- [Building a Chat App with the Vercel AI SDK](/products/ai-studio/agent-channels/building-an-app) — the application side.
- [What an Agent Channel Chat Can Reach](/products/ai-studio/agent-channels/channel-chats) — what the channel's chats can and cannot do.
- [Shared Work Folders](/products/ai-studio/shared-folders/) — work modes and who manages a folder.