User Credentials
Let agents act for each end user with that person's own account, through OAuth sign-in or an API token, in MCP servers and custom tools.
On this page
How It Works
Some services accept only the token of the person an agent works for, with no shared API key. A user credential defines how end users connect their account in an environment. Each end user connects once, connic stores their token encrypted, and runs for that user hand it to MCP servers and custom tools.
- OAuth sign-in: users sign in with the provider, and connic refreshes their tokens.
- API token: users paste a token they created in the service, or your backend stores it.
Set Up
- Add the credential under Settings → User Credentials & Passkeys and pick its type. For OAuth sign-in, register an OAuth client with the provider using the redirect URL shown there, then enter its authorization URL, token URL, client ID, client secret and scopes. If the token URL is only reachable inside your network, select a Bridge. connic does not discover authorization servers or register clients automatically. For either type, add the return URLs of your application.
- Identify the end user in every run. Set a context value with their ID in middleware after verifying the user, and use the same ID when they connect.
async def before(content, context):
payload = context.get("payload", {})
context["user_id"] = await verify_user(payload["session_token"]) # your own check
return contentConnecting Users
Connect link from your application: create a link with the REST API, for example behind a Connect button in your settings page. The user signs in with the provider or pastes their API token, then returns to return_url with connic_oauth=connected, denied, or failed in the query. Without a return_url, connic shows a confirmation page. Links work once and expire after 10 minutes.
curl -X POST "https://api.connic.co/v1/projects/{project_id}/user-credentials/{credential_id}/connect-links" \
-H "Authorization: Bearer cnc_your_api_key" \
-H "Content-Type: application/json" \
-d '{"user_id": "emp_42", "return_url": "https://app.example.com/settings/integrations"}'
# {"url": "https://api.connic.co/v1/oauth/start/...", "expires_at": "2026-10-12T10:10:00Z"}Token from your backend: if your application already has the user's API token, store it directly. Pass expires_at when the token stops working on a known date; after it, the user counts as not connected.
curl -X PUT "https://api.connic.co/v1/projects/{project_id}/user-credentials/{credential_id}/users" \
-H "Authorization: Bearer cnc_your_api_key" \
-H "Content-Type: application/json" \
-d '{"user_id": "emp_42", "token": "<API token>", "expires_at": "2026-12-21T00:00:00Z"}'From a conversation: an MCP server with connect_tool: true gives the agent a tool that returns a connect link for the current user. See MCP servers.
The settings page and the REST API list connected users and disconnect them. connic MCP offers list_user_credentials, list_user_credential_users, revoke_user_credential_user, and create_user_credential_connect_link. It has no tool that stores a token, so tokens never pass through a model.
Using the Token
In MCP Servers
Reference the credential from the server. connic sends the user's token as Authorization: Bearer and leaves the server out for users who have not connected. MCP servers covers the details.
mcp_servers:
- name: sisense
url: https://bi.example.com/mcp
credential:
name: sisense
user: context.user_idIn Custom Tools
user_credential returns the user's current token, or None when they have not connected or the token has expired. Traces mask the token. After the service rejects it, pass it back as rejected: connic refreshes an OAuth token, or deletes a pasted one so the user connects again.
import httpx
from connic.tools import user_credential
async def list_dashboards(context: dict) -> dict:
token = await user_credential("sisense", context["user_id"])
if token is None:
return {"error": "Connect your Sisense account first."}
async with httpx.AsyncClient() as client:
response = await client.get(
"https://bi.example.com/api/v1/dashboards",
headers={"Authorization": f"Bearer {token}"},
)
if response.status_code == 401:
await user_credential("sisense", context["user_id"], rejected=token)
return {"error": "The Sisense token stopped working. Connect your account again."}
return {"dashboards": response.json()}Tokens Over Time
- OAuth tokens that expire within five minutes are refreshed first when the provider issued a refresh token.
- A token past its expiry with no refresh token counts as missing, and the user connects again.
- A rejected token without a refresh token is deleted.
- Connecting again replaces the stored token. Deleting a credential deletes the tokens of all its users.
- The REST API and connic MCP never return token values.
Permissions
Seeing credentials and their users takes View user credentials and connected users. Changing credentials and disconnecting users takes Manage user credentials and connected users. Storing tokens and creating connect links takes Set user tokens and create connect links. See Team and permissions.