How to create a VTEX app key and token for Zendesk

By Jake Marsh · Updated November 13, 2026

To connect VTEX to Zendesk, create a role in the VTEX admin under Account settings > Account management > Roles with the OMS resources View order and List Orders, then open Application keys, generate a key with that role and copy the app key and app token. Paste both, with your VTEX account name, into Feirawell's settings in Zendesk. VTEX shows the token only once.

Steps

Create a role. In the VTEX admin, open Account settings > Account management > Roles and click New role. Name it something you will recognize, such as "Zendesk Feirawell".
Add the resources the sidebar needs. Under OMS, add View order and List Orders. That is enough for agents to see orders.
Add resources for the actions you plan to allow (see the table below). Leave out anything you won't turn on.
Generate the key. Open Application keys, generate a key, give it the role and copy the app key and app token right away.
Install Feirawell from the Zendesk Marketplace and fill in VTEX account name (mystore for mystore.myvtex.com), App key and App token.
Test it. Open a ticket from a customer who has ordered. Their VTEX orders should appear in the sidebar.

Which resources each feature needs

Feature in Feirawell	VTEX License Manager resource	Setting in Zendesk
See orders in the sidebar, look orders up	OMS: View order, List Orders	Always on
Add order note	Checkout: Orders Full Access	Allow order notes (on by default)
Start handling	OMS: Change order workflow status	Allow start handling (off by default)
Cancel order	OMS: Change order workflow status, plus OMS: Cancel order, which VTEX's API reference lists for its cancel endpoint	Allow cancelling (off by default)

VTEX's own guidance is to create a custom role with only the resources an integration needs instead of a predefined role, which usually grants many more. See VTEX's best practices for application keys.

Where Zendesk keeps the key

The app key and token are Zendesk secure settings. Agents never see them. Zendesk's proxy inserts them into request headers only for mystore.vtexcommercestable.com.br, the account you named, so the browser never holds them.

More than one VTEX account

Feirawell connects up to three VTEX accounts, each with its own key. Create a key in each account, then fill in VTEX account name (account 2) and its key and token, and the same for account 3. Each account also takes:

Account label: the name agents see in the sidebar and ticket notes.
Account brands: Zendesk brand ids, comma separated, whose tickets open this account first.

Agents switch accounts at the top of the sidebar.

Error messages and fixes

What you see	Cause and fix
401	The key or token is wrong or was revoked. Generate a new key and paste both values.
403	The key's role is missing a resource above, usually the one for the action that failed. Add it to the role.
404, or a web page instead of VTEX data	The account name is wrong. Use only the first part of mystore.myvtex.com.
No orders found	See the limits of VTEX's order search in the Feirawell documentation, and look the order up by id.

What it costs

Feirawell for VTEX is $9 per agent per month, one plan with every feature, after a 14-day free trial. Zendesk asks for a card at install and bills it monthly. VTEX app keys cost nothing extra on VTEX's side.

Feirawell for VTEX

Your customer's VTEX orders by email or CPF: items, Pix and boleto, invoices, tracking. $9/agent. $9 a month per agent.

Install Feirawell for VTEX About Feirawell for VTEX Documentation

Questions

I lost the app token. Can I see it again?

No. VTEX shows the token once. Generate a new key with the same role and paste the new key and token into Feirawell.

Can I use a predefined role like OMS full access?

It works, but it grants far more than Feirawell uses. A custom role with View order and List Orders, plus only the action resources you turn on, keeps the key narrow.

Does Feirawell need a VTEX app installed in my store?

No. It calls VTEX's OMS API with the key you create. Nothing is installed in VTEX.