OAuth Authentication
Some MCP servers require OAuth 2.0 authentication to access third-party APIs on behalf of users. For example, a Dropbox MCP server needs a user’s Dropbox access token to read and write files. TeamWeb AI supports the OAuth 2.0 Authorization Code flow with PKCE for these servers.
How It Works
- An admin configures OAuth credentials (client ID, secret, endpoints) on the MCP server.
- An admin or user completes the OAuth consent flow to authorize TeamWeb AI.
- TeamWeb AI stores the access and refresh tokens (encrypted at rest).
- When the assistant calls a tool on that server, TeamWeb AI attaches the Bearer token automatically.
- Tokens are refreshed automatically before they expire.
Token Sharing Modes
Each OAuth-enabled MCP server is configured with one of two sharing modes:
| Mode | Behavior |
|---|---|
| Shared | One token for all users. An admin authorizes once and all assistants use that token. |
| Per User | Each user authorizes separately. Users are prompted inline in chat when they first use a tool that requires authorization. |
Shared is best for service accounts or organization-wide access (e.g., a shared Dropbox folder). Per User is best when the server acts on behalf of individual users (e.g., accessing a user’s personal files).
Configuring OAuth
Navigate to MCP Servers > New MCP Server (or edit an existing one). Under the Authentication section, select OAuth 2.0.
Required Fields
| Field | Description |
|---|---|
| Client ID | OAuth application client ID from the provider |
| Client Secret | OAuth application client secret |
| Authorization URL | Provider’s authorization endpoint (must be HTTPS) |
| Token URL | Provider’s token endpoint (must be HTTPS) |
Optional Fields
| Field | Description |
|---|---|
| Scopes | Space-separated OAuth scopes to request |
| Token Sharing | Shared (default) or Per User |
Setting Up the OAuth Application
At the OAuth provider (e.g., Dropbox, Google, GitHub), create an OAuth application and configure the callback URL as:
https://your-teamweb-domain.com/oauth/callbackMake sure the PUBLIC_URL environment variable in your TeamWeb AI deployment matches the domain you register with the provider.
Authorizing
Shared Mode
After creating the server, visit the server’s detail page and click the Authorize button. You’ll be redirected to the OAuth provider to grant access. After approval, you’re returned to TeamWeb AI and the token is stored.
The detail page shows the token status:
- Connected — Token is valid (with expiry date if applicable)
- Expired — Token has expired and needs re-authorization
- Not connected — No authorization has been completed yet
Per-User Mode
For per-user servers, users are prompted inline during chat when they first try to use a tool that requires authorization. The assistant provides an authorization link. After completing the flow in a browser tab, the user can return to their conversation and retry the tool.
Token Refresh
TeamWeb AI handles token refresh automatically:
- On-demand — When a tool call is made and the token is about to expire, a refresh request is sent to the provider before the tool call proceeds.
- Proactive — A background task checks every 5 minutes for tokens expiring within 10 minutes and refreshes them preemptively.
If a refresh fails (e.g., the refresh token has been revoked), the last error is shown on the server’s detail page. For shared servers, an admin can click Authorize to re-authorize. For per-user servers, the user will be prompted again in chat.
Revoking Tokens
Click the Revoke button on the server’s detail page to delete all stored tokens. This is useful when rotating credentials or decommissioning a server. After revoking, re-authorization is required.
Credential Encryption
All MCP credentials (OAuth tokens, client secrets, environment variables, and headers) are encrypted at rest using AES-256-GCM. See Secret Storage for details on configuring the encryption key.