Credentials for agents

Follow Create an app and a credential and create a separate application or credential for each agent, so it can be revoked on its own.

Choose scopes

Start read-only and add scopes as the agent’s tasks need them.

Agent task	Scopes	Data access flags
Explore what’s available	website_read	none
Investigate conversations and transcripts	website_read, conversation_read, message_content_read, contact_read_pii	message_content, pii
Look up contacts	website_read, contact_read, plus contact_read_pii for names and emails	pii for personal fields
Report on AI-handled conversations	website_read, reports_read, conversation_read	none, or message_content and pii for content-based measures
Review AI feature configuration	website_read, config_read	none
Follow change events	website_read, event_read	none

Contacts, configuration, AI features and event tools need an unrestricted application, with no channel, team or subsite restrictions.

Choose how the agent authenticates

Option	How it works	Trade-off
Installation token, recommended to start	The agent sends the credential’s igw_live_... token on every request.	Simplest setup. The token lasts until the credential expires, so use a short expiry.
Short-lived OAuth token	A helper exchanges the credential for a 15-minute token bound to /mcp, and fetches a new one when it expires.	Tokens sent to the server are short-lived, work only at MCP, and can be narrowed to fewer scopes. The client secret still has to be on the machine.

Why the built-in login button doesn't work

The Gateway’s browser sign-in flow is for hosted, confidential web applications with registered HTTPS callbacks. It doesn’t support dynamic client registration, public clients or loopback callbacks. Desktop and command-line agents therefore can’t use their built-in “log in” button with the Gateway; use one of the two options above.

Keep the token out of config files

Store the token in an environment variable and reference it from the client configuration:

Client	Reference
Codex	bearer_token_env_var = "INSIDE_GATEWAY_TOKEN"
Claude Code	"Authorization": "Bearer ${INSIDE_GATEWAY_TOKEN}"
Cursor	"Authorization": "Bearer ${env:INSIDE_GATEWAY_TOKEN}"

Config files that use these references are safe to commit.