Choose API scopes for an AI agent
On this page
Use this article to choose the API Scopes on a Store Role so a person’s AI agent gets the tools they need for their work. Scopes decide which tools an agent is shown. An agent never sees a tool the person’s scopes do not allow, so it cannot try one and fail.
Before you start
- You can create and edit Store Role records, and the API Scopes field is on your Store Role page layout. See Store roles.
- Agent access is turned on for the person. See Manage who can use an AI agent.
How scopes reach an agent
- Only a
Content Changesrole atEditororApproverlevel lets an agent connect. ACommenterrole, or aWeb Consolerole on its own, does not. - A role with no API Scopes still lets the agent connect, but the agent gets no tools. The agent shows the connection as active and can still show StoreConnect’s instructions and guided prompts, because those do not depend on scopes. It is not told why the tools are missing.
- A role you create starts with nothing selected. Only the installed Content Editor and Content Approver roles arrive with scopes.
- Scopes add up across every role the person holds on the store. That includes
Web ConsoleandCommenterroles. Leave API Scopes empty on roles that are not meant to give agent access, or they widen what the agent can do. - Scopes are not limited by the person’s own permissions. For example,
Catalog (Write)lets the agent stage product and price changes even if the person cannot edit products in Salesforce or the Website Builder. The approver’s review controls what reaches the store, because an approved change is applied whatever access the person who drafted it has. - A signed-in agent keeps the scopes it had when it signed in, for up to about eight hours. After you change scopes, the person removes the StoreConnect connection from their agent, adds it again, and signs in with their existing token. See Manage who can use an AI agent.
- To cut access straight away, remove the person’s role for the store or turn off their agent access. Both take effect on the agent’s next request. Removing a scope only takes effect when the person next signs in.
What each scope gives an agent
Every change an agent makes through the StoreConnect connection is staged in a draft and sent for review, not published live. A person with an Approver level role publishes the change in Salesforce. See Review and approve a content change.
| Scope | What the agent can do |
|---|---|
Store (Read) |
Read the store’s details. The agent uses this to confirm which store it is connected to. |
Content (Read) |
Read pages, articles, article categories, content blocks, menus and the design brief. List and open content changes, including the agent’s own drafts. |
Content (Write) |
Stage changes to pages, articles, article categories, content blocks and menus. Stage changes to the store’s own settings: name, SEO defaults, logo, favicon, home page, header and footer menus, and custom styles (site-wide CSS). Get a link to open the draft in the Website Builder. |
Catalog (Read) |
Read products, variants, categories, traits and media (images and files). Get an upload link for a new image or file. |
Catalog (Write) |
Stage changes to products, variants, prices, categories and media. Adding a new image or file to the store needs this scope. |
Themes (Read) |
Read themes, theme templates and theme assets. |
Themes (Write) |
Stage changes to themes, theme templates, theme assets and theme variables, and stage a theme activation. |
Publish Staged Changes |
Send the agent’s draft for review, withdraw it, and get a preview link. Any write scope already allows all three, so this scope only matters on a role with no write scopes. |
Extraction (Read) |
Crawl and capture an existing website so the agent can rebuild it in your store. Site extraction is off by default. To use it, contact StoreConnect Support to turn it on for your website. Until then, the agent does not list these tools, even with this scope. |
Publish Own Changes |
Applies in Salesforce, not to the agent. Lets an Approver publish a content change they submitted themselves. Without it, someone else must publish it. With it, an approver can publish changes their own agent drafted, with no second person reviewing them. Leave it off where every agent change should be checked by someone else. |
:::note Images and files belong to the Catalog scopes, not Content. A role with Content scopes but no Catalog (Write) can place images that are already in the store, but cannot add new ones. :::
The agent can also take a screenshot of a page in the draft when it has Content (Write). Screenshots are off by default. To use them, contact StoreConnect Support to turn them on for your website.
Scopes that add no agent tools
Carts, Checkout, Contacts, Accounts, Payment Methods and Subscriptions add no tools to an agent. They apply only to direct calls to the website API, where the same personal access token can read and change customer contacts, accounts, saved payment methods and subscriptions, and charge a cart.
Leave them off Content Changes roles. Selecting every scope gives an agent no more tools than the Content Editor role does, but lets anyone holding the person’s token reach customer data and take payments through the API.
Example roles
Each example is a Store Role with Type Content Changes and Level Editor. Use Approver for a person who also publishes changes in Salesforce. Every example includes Store (Read), so the agent can confirm which store it is working on.
Full site builder
Content (Read), Content (Write), Catalog (Read), Catalog (Write), Themes (Read), Themes (Write), Publish Staged Changes, Store (Read), Extraction (Read)
The agent gets every agent tool, except screenshots and site extraction until StoreConnect Support turns them on. These are the scopes on the installed Content Editor and Content Approver roles. Use this for a person who builds or redesigns the whole store.
Content writer
Content (Read), Content (Write), Catalog (Read), Store (Read)
The agent works on pages, articles, content blocks and menus, and can browse products and place existing images. It cannot add new images, and it cannot change products or themes.
Content (Write) also covers the store’s settings, including the home page, header and footer menus and site-wide CSS. If the person should not change those, review their drafts before approving. To let them upload images, add Catalog (Write), which also lets them stage product, price and category changes.
Catalog manager
Catalog (Read), Catalog (Write), Content (Read), Store (Read)
The agent works on products, variants, prices, categories and images. Content (Read) is included so the agent can list and open the agent’s own drafts. Without it, the agent can still stage and send changes for review, but cannot see the draft it is working in.
Theme developer
Themes (Read), Themes (Write), Content (Read), Content (Write), Store (Read)
The agent works on theme templates, assets and variables. Content (Write) is included because site-wide CSS, the Website Builder link and screenshots all depend on it. It also lets the agent stage page and menu changes.
For a theme-only role, leave out Content (Write). The agent then cannot change site-wide CSS, open the Website Builder or take screenshots.
Read-only reviewer
Content (Read), Catalog (Read), Themes (Read), Store (Read)
The agent can read and audit the store, but cannot stage or send any change. This limits the agent only. An Editor level role still lets the person make changes themselves in the Website Builder.
Set the scopes on a role
- Open the Store Role record.
- In API Scopes, move the scopes for the role into the selected list. For example, for a content writer, select
Content (Read),Content (Write),Catalog (Read)andStore (Read). - Save the record.
- Ask each person who holds the role to remove the StoreConnect connection from their agent, add it again, and sign in with their existing token.
The person’s agent now lists tools for the selected scopes only. For example, a content writer’s agent lists page and menu tools, and no theme tools.
Frequently asked questions
The agent connects but shows no tools. What is wrong?
None of the person’s roles for that store has any API Scopes selected. Open the Content Changes role assigned to that person for that store, not another role with the same name or level, and check that API Scopes shows values after you save. Then ask the person to reconnect. If API Scopes already shows values and the person still sees no tools after signing in again, contact StoreConnect Support. The store may not have received the role’s scopes from Salesforce. See Troubleshoot an agent connection.
The store lists every scope as supported. Does my token carry all of them?
No. The store’s public sign-in information (/.well-known/oauth-protected-resource) lists every scope the store understands. It says nothing about any one person. A person’s agent gets only the scopes on their own roles for that store.
Can a role let an agent publish changes live?
Not through the StoreConnect connection. There, an agent only sends changes for review. A person with an Approver level role publishes them in Salesforce. Publish Own Changes lets that person publish a change they submitted themselves, but it does not let the agent publish. An agent that can make its own web requests, such as a coding assistant, can also use the person’s token to call the website API directly, within the person’s scopes. See Scopes that add no agent tools.
Was this article helpful?
Thanks for your feedback! It helps us improve our docs.