API keys and access
How sign-in, API keys, permissions and connection limits decide what can be read.
Everything in EcomSquad belongs to an organization: your team’s boundary for membership and data. Platform also calls it a workspace. Access is always decided by EcomSquad from your sign-in or key; you never send an organization ID.
Ways in
| Credential | Who uses it | Where |
|---|---|---|
| Sign-in | People | Platform, OneInbox, and assistants that support MCP sign-in. |
| API key | Servers and some MCP clients | The Context API and MCP. |
Sign-in uses a link sent to the email address your administrator provisioned. Requesting a link does not create access; you must already be a member. An assistant signed in as you uses your permissions, narrowed by what you approve.
An API key belongs to the organization and works until it expires or is revoked. Keep it out of browser code, repositories, and chat messages.
Create a key
You need permission to create API keys and the names of the mailbox and store your integration should access.
Name the integration
In Platform, open API keys → Create key. Enter a recognizable Name, such as “Support reporting”. Use a separate key for each integration.
Choose permissions
Choose Custom, keep Support context → Read checked, and clear the other permissions you do not need. Custom starts from the current selection. You cannot grant permissions your own membership does not have. The key keeps following your role: if your role is lowered, it loses what the new role does not have, and if you leave the organization, it stops working.
Set expiry and connection access
Choose 30 days, 90 days, or 1 year under Expires.
Under Account access, choose Only selected accounts. Select the relevant mailbox and Shopify store to read a ticket with its orders.
Check the connection selection
All accounts includes future connections. If Account access is absent, the key will use all-connection access. Resolve the missing or unavailable connection list before creating a key that needs limits.
Save the secret
Choose Create key. Copy the secret into your integration’s secret manager or private environment configuration before choosing Done. The secret is shown once; a lost secret needs a replacement key.
Send the key in the x-api-key header, not an OAuth bearer-token field, then
follow the Quickstart to check that it reads the intended
connections.
Permissions
| Permission | What it allows |
|---|---|
Support context → Read (context:read) | Read stored tickets, messages, customers, and orders. |
Support context → Refresh (context:refresh) | Ask the store for current order information and store the results. Always includes Read. |
Inbox → Read changes (inbox:read) | Poll the Needs reply feed. Only owners and admins can add it; no preset includes it. |
Inbox → Refresh mailboxes (inbox:refresh) | Ask for a mail check of the mailboxes the key reaches, and read its status. Always includes Read changes. Only owners and admins can add it; no preset includes it. |
When creating a key, Read only includes more than support context and Full access includes further actions. Choose Custom to select only what your integration needs.
Some keys created before the Context API existed lack context:read, even if they
came from the read-only preset. Replace them.
Connection limits
Connection limits decide which sources a key can read.
- Only selected accounts limits the key to the mailboxes and stores you pick.
- All accounts includes every connection, including ones added later.
A key that can read a mailbox but not its store still reads the ticket, without
the orders in that store, and a refresh reports not_permitted. Scope a key to
both the mailbox and the store to read a ticket with its orders.
Replace or revoke a key
For routine replacement:
- Create a new key with the required permissions and connections.
- Update the integration and confirm that a read succeeds.
- Choose Revoke on the old key and confirm.
For a leaked key, revoke it immediately, then configure a replacement. Revocation stops authentication with that key without disconnecting sources or deleting data. To change permissions or connection limits through Platform, create a replacement.
Common problems
- Create key is unavailable: ask an organization administrator to create a key with the permissions and connection limits you need.
- The ticket loads without its orders, or a refresh reports
not_permitted: the key may include the mailbox but omit the Shopify store. Replace it with one scoped to both.
For authentication failures, see API troubleshooting. Reading documentation never grants access to an organization’s data.