Skip to main content

API Tokens

API tokens provide secure, programmatic access to your organization's resources. Tokens are scoped to your organization and can be created with fine-grained permission scopes to limit access.

Manage them from Admin > API Tokens. Each token shows its scopes, when it was created, and when it was last used, with actions to edit or revoke it.

API Tokens page listing a token with its scope badge, created date, and last-used time, plus edit and revoke icons and a Generate Token button

Current Capabilities​

API tokens support:

  • Admin API – Manage MCP servers, toolkits, skills, users, groups, policies, and commands
  • SCIM Provisioning – Automate user and group management from your identity provider (Okta, Azure AD, etc.)
  • User API – Access user-scoped resources such as toolkits, skills, commands, and connections

See the API Reference for full endpoint documentation.

Generating a Token​

  1. Go to Admin > API Tokens
  2. Select Generate Token
  3. Enter a descriptive name (for example, "Okta SCIM Integration")
  4. Select the permission scopes for the token
  5. Select Generate
  6. Copy your token immediately – it will not be shown again
Generate API Token modal with a Token Name field and Permission Scopes checklist including all, admin:read, admin:write, admin:scim, connect:read, connect:write, and connect:exchange-auth
Security Notice

The token is displayed only once after generation. Store it securely. If you lose the token, you'll need to generate a new one.

Permission Scopes​

When generating a token, you choose which scopes it should have. This follows the principle of least privilege: only grant the access a token needs.

ScopeDescription
allFull access to all API operations
admin:readRead-only access to admin resources (MCP Servers, Toolkits, Skills, Users, Groups, Policies, Commands)
admin:writeRead & write access to admin resources (includes admin:read and admin:scim)
admin:scimSCIM provisioning access only
connect:readRead-only access to user-scoped resources (User API)
connect:writeRead & write access to user-scoped resources (includes connect:read and connect:exchange-auth)
connect:exchange-authExchange external JWTs for Connect credentials (auth exchange API)

Scope Hierarchy​

Broader scopes automatically include narrower ones:

  • all includes every scope
  • admin:write includes admin:read and admin:scim
  • connect:write includes connect:read and connect:exchange-auth

Choosing Scopes​

Use CaseRecommended Scope
Full automation (CI/CD, scripts)all
Okta / Azure AD SCIM syncadmin:scim
Read-only monitoring / auditingadmin:read
Infrastructure-as-code (Terraform, Pulumi)admin:write
MCP client plugins (read user resources)connect:read
MCP client plugins (manage user toolkits)connect:write

Using the Token​

Include the token in the Authorization header of your API requests:

curl -H "Authorization: Bearer wxt_xxxxx" \
  https://your-domain.example.com/api/users

For User API endpoints, also include a header that identifies which user to act as — either x-user-email (a regular user) or x-machine-user (a machine user's slug), but not both:

# Act as a regular user
curl -H "Authorization: Bearer wxt_xxxxx" \
     -H "x-user-email: user@example.com" \
  https://your-domain.example.com/api/skills

# Act as a machine user (bots, scripts, automations)
curl -H "Authorization: Bearer wxt_xxxxx" \
     -H "x-machine-user: ci-deploy-bot" \
  https://your-domain.example.com/api/skills

Token Format​

Tokens are prefixed with wxt_ followed by a cryptographically random string:

wxt_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abc

Security​

  • Hashed Storage – Tokens are hashed before being stored. The plain token is never persisted.
  • Organization Scoped – Each token is tied to a specific organization.
  • Permission Scoped – Each token is restricted to the scopes selected at creation time.
  • Usage Tracking – The system tracks when each token was last used.
  • Revocable – Tokens can be revoked instantly from the API Tokens page.

Editing a Token​

You can rename a token or change its permission scopes after it has been created. The token value itself does not change, so integrations using it keep working.

  1. Go to Admin > API Tokens
  2. Select the edit (pencil) icon next to the token
  3. Update the token name or permission scopes
  4. Select Save
Edit API Token modal for updating a token's name or permission scopes, with Cancel and Save actions

Revoking a Token​

  1. Go to Admin > API Tokens
  2. Select the revoke (trash) icon next to the token
  3. Confirm the revocation
Revoke API Token confirmation warning that any integrations using the token will stop working immediately, with Cancel and Revoke Token actions

Revoking a token immediately invalidates it. Any integrations using that token will stop working, and the action cannot be undone.

Best Practices​

  • Use descriptive names – Name tokens after their purpose (e.g., "Okta SCIM", "Azure AD Sync")
  • Use minimal scopes – Only grant the scopes a token actually needs
  • Rotate tokens periodically – Generate new tokens and revoke old ones on a regular schedule
  • Use separate tokens – Create different tokens for different integrations, each with their own scopes
  • Monitor usage – Check the "Last used" timestamp to identify unused tokens
  • Revoke unused tokens – Remove tokens that are no longer needed

Backward Compatibility​

Existing tokens created before scopes were introduced are treated as having the all scope and continue to work without any changes.

On-Premises Deployments​

For on-premises deployments, you can alternatively use the AUTH_SECRET environment variable for SCIM authentication. This provides backward compatibility for simpler setups that don't require multiple tokens. The AUTH_SECRET has full access equivalent to the all scope.

See SCIM Provisioning for more details on configuring SCIM endpoints.

On this page