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.
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
- Navigate to Admin Settings in your organization
- Find the API Tokens section
- Click Generate Token
- Enter a descriptive name (e.g., "Okta SCIM Integration")
- Select the permission scopes for the token
- Click Generate
- Copy your token immediately – it will not be shown again
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.
| Scope | Description |
|---|---|
all | Full access to all API operations |
admin:read | Read-only access to admin resources (MCP Servers, Toolkits, Skills, Users, Groups, Policies, Commands) |
admin:write | Read & write access to admin resources (includes admin:read and admin:scim) |
admin:scim | SCIM provisioning access only |
connect:read | Read-only access to user-scoped resources (User API) |
connect:write | Read & write access to user-scoped resources (includes connect:read) |
Scope Hierarchy
Broader scopes automatically include narrower ones:
all— includes every scopeadmin:write— includesadmin:readandadmin:scimconnect:write— includesconnect:read
Choosing Scopes
| Use Case | Recommended Scope |
|---|---|
| Full automation (CI/CD, scripts) | all |
| Okta / Azure AD SCIM sync | admin:scim |
| Read-only monitoring / auditing | admin: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 the x-user-email header:
curl -H "Authorization: Bearer wxt_xxxxx" \
-H "x-user-email: [email protected]" \
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 Admin Settings.
Revoking a Token
- Navigate to Admin Settings
- Find the token in the API Tokens list
- Click the trash icon next to the token
- Confirm the revocation
Revoking a token immediately invalidates it. Any integrations using that token will stop working.
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.