Authentication

Every API request carries a token in the Authorization header:

Authorization: Bearer msv_pat_…

There are three kinds of token. Each starts with a recognisable prefix, so secret scanners can spot one that leaked.

Prefix	What it is	Made in	Acts as
`msv_pat_`	A personal token	Settings → Developer	You
`msv_bot_`	An app token	Org Settings → Integrations → Apps & bots	The app's bot user, in one org
`msv_oat_`	An OAuth access token	The OAuth flow	The installed bot, or the person who signed in

A token can never do more than the person or bot it acts as. Scopes only narrow what it may do.

Personal tokens

A personal token acts as you, for scripts and automations. Make one in Settings → Developer (on a phone: You → Developer).

Scopes. Pick only what the script needs. What the token can do is your own permissions, narrowed by its scopes.
Org pin. You can pin a token to one org. Unpinned, it reaches every org you're in (that allows it; see below).
Expiry. A personal token expires after 90 days unless you choose otherwise: 7, 30, 90 or 180 days, a year, or never. A token that never expires keeps working until you revoke it.
Shown once. The token is shown only when you make it. Afterwards the list shows a hint (its prefix and last four characters), when it was last used and from where. If you lose it, revoke it and make a new one.
Limit. You can hold up to 25 live personal tokens.

Direct messages

A personal token never reads your direct messages or group chats unless you tick Include my direct messages when you make it. Without the tick, those conversations don't exist for the token: they don't appear in lists and fetching one answers 404. An app token never reads direct messages or group chats, whatever its scopes.

When an org keeps personal tokens to owners and admins

An org's Owners and Admins can decide that only they may use personal tokens there: Org Settings → Integrations → API tokens → Members may make personal API tokens. While that is off:

Members and Guests can't make a personal token pinned to that org.
Their existing tokens stop reaching that org at once. The tokens aren't revoked: they keep working in the member's other orgs, and they reach this org again if the setting is turned back on.
App tokens are not affected.

App tokens

An app token belongs to an installed app. It posts as the app's bot user, in one org, with the scopes the install was given. Make one under Org Settings → Integrations → Apps & bots: open the app and choose Make token. You need the Manage integrations permission (Owners, Admins, or a custom role that grants it).

An app token sees the org's public text channels and the channels the app was added to. It reads message content only in the channels it was added to, unless an admin gave it messages:read:all. It never sees direct messages, group chats or people's email addresses. App tokens don't expire unless you set an expiry. See Apps and bots.

OAuth access tokens

Apps that other orgs connect get tokens through OAuth: msv_oat_… access tokens (valid for an hour) and msv_ort_… refresh tokens, which change on every refresh. Use the access token exactly like an API token. An install token acts as the bot, like an app token; a sign-in token acts as the person, within the scopes they granted. See OAuth.

Scopes

Each operation in the reference names the scope it needs. identify is part of every token.

Scope	Lets the token
`identify`	Read who the token is, its orgs and scopes (`GET /v1/me`). Every token has it.
`channels:read`	List and read channels you can see, and an app's channel list.
`channels:write`	Create channels, and add apps to or remove them from channels you manage.
`messages:read`	Read messages in channels you can see, search, and download attachments.
`messages:read:all`	Read every channel in the org, including private ones you aren't in. Owner/Admin only.
`messages:write`	Post, reply in threads, and edit or delete the token's own messages.
`reactions:write`	Add and remove reactions.
`members:read`	List members, their roles and titles, and custom roles.
`roles:write`	Give and take custom roles (never the Owner / Admin / Member / Guest role). Owner/Admin only; an app keeps it only while the person who set it up is an Owner or Admin, and can't give a role that manages integrations.
`meetings:read`	Read the meetings you're in or organise.
`meetings:write`	Schedule meetings as you, and change, re-invite or cancel the ones you organise. Personal tokens only.
`shifts:read`	Read your published shifts and the org's events.
`tasks:write`	Add tasks to your list.
`files:write`	Upload files to attach to messages. See Files.
`webhooks:write`	Manage the org's incoming webhooks. Owner/Admin only; needs Manage integrations.
`events:subscribe`	Manage event subscriptions and read stored events. Owner/Admin only; needs Manage integrations.
`commands:write`	Register an app's slash commands. Apps only.
`admin:read`	Export the org's audit log. Owner/Admin only.
`mcp:read`	Let an AI assistant read through the MCP server, as you.
`mcp:write`	Let an AI assistant act (post, react, add tasks, schedule meetings) through the MCP server. Includes `mcp:read`.

Owner/Admin only means a personal token gets the scope only when its owner is an Owner or Admin: of the pinned org, or of some org when the token is unpinned. messages:read:all includes messages:read.

The scope list also contains presence:read. No API operation uses it yet.

Revoking a token

Personal tokens: revoke one in Settings → Developer. It stops working at once.
App tokens: revoke one on the app's card in Apps & bots. Pausing or uninstalling the app stops its tokens too.
OAuth: the person can disconnect an app in Settings → Connected apps; your app can call the revocation endpoint. See OAuth.
A personal token pinned to an org stops working for good if its owner leaves that org.

When a request is refused

Status	`code`	Meaning
`401`	`unauthenticated`	No token was sent.
`401`	`token_invalid`, `token_revoked`, `token_expired`	The token isn't valid any more.
`401`	`account_suspended`	The account behind the token is suspended.
`403`	`insufficient_scope`	The token lacks the scope the operation needs.
`403`	`org_not_allowed`	The token can't act in that org (another org, its pin, or the org's personal-token setting).
`403`	`forbidden`	The person or bot may not do this.
`404`	`not_found`	It doesn't exist, or this token can't see it. Other orgs' things always read as not found.

Keep tokens out of source control, logs and URLs. If one leaks, revoke it.