Civic Tokens

Civic tokens provide a way to authenticate with Civic from services that don't support browser-based OAuth flows, such as OpenAI Agent Builder, workflow automation platforms, and custom applications.

note

Most users don't need tokens - If you're using Claude Desktop, VS Code, Cursor, or other MCP-compatible desktop agents, use browser authentication instead. Tokens are only needed for specific use cases described below.

What are Civic Tokens?

Civic tokens are temporary access tokens that grant permission to use your Civic MCP servers from external services. They are:

• Profile-scoped: Each token is tied to a specific Civic profile (toolkit)
• Time-limited: Tokens expire after a configurable period (up to 30 days)
• Delegated: Tokens are delegated credentials that allow external services to act on your behalf
• Secure: Tokens use industry-standard OAuth 2.0 token exchange (RFC 8693)

note

What is a delegated token? A delegated token allows an external service or application to access your Civic resources on your behalf. The service acts with the same permissions you have, but the token is scoped to a specific profile (toolkit) to limit what resources can be accessed.

When to Use Tokens vs Browser Auth

Use Browser Authentication

Browser authentication works well for interactive use cases:

Desktop AI Agents

Claude Desktop, Cursor, VS Code - authenticate through your browser

Interactive Sessions

Any client where you can complete an OAuth flow in your browser

Use Token Authentication

Generate a token when you need to:

Agent Builders

OpenAI Agent Builder - Requires token upfront for authentication

Automation Platforms

n8n and similar workflow tools that run server-side

Custom Applications

Server-to-server integrations - Your own apps and services

Restricted Environments

CI/CD, scripts - Where browser OAuth isn't available

Why these services need tokens:

Tokens are appropriate for background processes such as autonomous agents, scheduled tasks, or other unattended workflows. These services:

• Run server-side without browser access for OAuth flows
• Require credentials configured ahead of time
• Can't trigger interactive authentication during execution
• Need persistent authentication for automated operations

How to Generate a Token

1. 1
   Navigate to Install page

   Go to app.civic.com and click on the Tools menu, then select Install

2. 2
   Select your toolkit

   Choose the profile (toolkit) you want to generate a token for. When you change the toolkit, the MCP URL will automatically update.

3. 3
   Click Install

   Click the Install button to generate your token

4. 4
   Set token expiration

   Choose how long the token should be valid (up to 30 days). The expiration date will be displayed based on your selection.

5. 5
   Copy and store securely

   After generating, copy the token immediately and store it securely

   warning

   Token displayed only once - The token is only shown once. If you lose it, you'll need to generate a new one.

Using Tokens in Different Services

OpenAI Agent Builder

When setting up an OpenAI agent that needs to access your Civic tools:

1. 1
   Create your agent

   In OpenAI Agent Builder, create a new agent or edit an existing one

2. 2
   Add MCP server

   Under Tools & Integrations, add a new MCP server connection

3. 3
   Configure the connection

   MCP URL: https://app.civic.com/hub/mcp?accountId=YOUR_ACCOUNT_ID&profile=YOUR_PROFILE_NAME
   Authentication: Bearer token
   Token: YOUR_CIVIC_TOKEN_HERE

4. 4
   Test the connection

   Save and test that your agent can access the Civic tools

tip

URL parameters:

• accountId - Your Civic account ID
• profile - The profile name (toolkit) that determines which MCP servers the agent can access
• lock - Whether to lock the session to the specified profile (true by default when a profile is set, false to allow profile switching)
• skills - Comma-separated list of skill aliases to load into the session

Use the profile alias you created in Civic.

n8n Workflows

To use Civic in your n8n automations:

1. 1
   Add HTTP Request node

   In your n8n workflow, add an HTTP Request node

2. 2
   Configure authentication

   URL: https://app.civic.com/hub/mcp?accountId=YOUR_ACCOUNT_ID&profile=YOUR_PROFILE_NAME
   Authentication: Header Auth
   Header Name: Authorization
   Header Value: Bearer YOUR_CIVIC_TOKEN_HERE

3. 3
   Set up MCP request

   Configure your MCP tool calls in the request body following the MCP protocol specification

Other Automation Platforms

Similar to n8n, other workflow automation platforms can use Civic tokens with HTTP modules and Bearer token authentication. The general pattern is:

URL: https://app.civic.com/hub/mcp?accountId=YOUR_ACCOUNT_ID&profile=YOUR_PROFILE_NAME
Authentication: Header Auth or Bearer Token
Header Name: Authorization
Header Value: Bearer YOUR_CIVIC_TOKEN_HERE
Content-Type: application/json

Custom Applications

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

curl 'https://app.civic.com/hub/mcp?accountId=YOUR_ACCOUNT_ID&profile=my-profile' \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

const response = await fetch('https://app.civic.com/hub/mcp?accountId=YOUR_ACCOUNT_ID&profile=my-profile', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.CIVIC_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/list'
  })
});

const data = await response.json();
console.log(data);

import requests
import os

headers = {
    'Authorization': f'Bearer {os.environ.get("CIVIC_TOKEN")}',
    'Content-Type': 'application/json'
}

payload = {
    'jsonrpc': '2.0',
    'id': 1,
    'method': 'tools/list'
}

response = requests.post(
    'https://app.civic.com/hub/mcp?accountId=YOUR_ACCOUNT_ID&profile=my-profile',
    headers=headers,
    json=payload
)

print(response.json())

Credential Access with Tokens

Civic tokens always result in a locked profile. This means the token can only access credentials that have been explicitly assigned to the profile. Unassigned credentials — even ones that would otherwise match — are not available.

warning

If you are rolling out token-based access for an existing profile, credentials that were previously resolved automatically (because the profile was unlocked) may now require explicit assignment. Check the authorizations dashboard to ensure your profile has the credentials it needs before switching to token authentication.

New credentials authenticated through a token session are automatically assigned to the token's profile.

Token Expiration & Renewal

Expiration

• You can configure token expiration up to a maximum of 30 days
• Expired tokens return a 401 Unauthorized error
• You'll receive no warning before expiration
• The expiration date is shown when you generate the token

Renewal

Tokens cannot be renewed. To continue access after expiration:

1. 1
   Generate a new token

   Follow the token generation steps above

2. 2
   Update your service

   Replace the old token with the new one in your service/application

3. 3
   Old token invalidated

   The expired token is automatically invalidated

tip

Best Practice: Set calendar reminders a few days before token expiration to avoid service interruption. Consider using shorter expiration periods for better security.

Security Best Practices

Storage

Never commit tokens to version control

Bad ❌

const token = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';

Good ✅

const token = process.env.CIVIC_TOKEN;

Always use environment variables and add .env to your .gitignore:

# .env (add to .gitignore!)
CIVIC_TOKEN=your_token_here

Use secret management services

For production environments, use dedicated secret managers:

• AWS Secrets Manager - For AWS deployments
• HashiCorp Vault - For multi-cloud or on-premises
• Google Secret Manager - For GCP deployments
• Azure Key Vault - For Azure deployments

Rotate tokens regularly

• Generate new tokens before old ones expire
• Don't wait until the last day
• Update services with new tokens proactively
• Test that the new token works before the old one expires

Rotate tokens before expiration

• Tokens can be configured for up to 30 days
• Set reminders to rotate tokens before they expire
• Generate new tokens proactively to avoid service interruption
• Use shorter expiration periods for better security
• Consider your organization's security policies and compliance requirements

Access Control

One token per service

Generate separate tokens for different services to isolate potential breaches

Use appropriate profiles

Create dedicated profiles for specific use cases with only necessary tools

Use shorter expiration periods

Configure tokens with shorter lifetimes when possible for better security

Monitor token usage

Check the Activity page for unexpected usage patterns

Troubleshooting

401 Unauthorized

Cause: Token is expired, invalid, or incorrectly formatted

Solutions:

• Verify token is correctly copied (no extra spaces or line breaks)
• Check token hasn't expired
• Generate a new token if needed
• Ensure Authorization header format: Bearer YOUR_TOKEN (note the space after "Bearer")
• Verify you're using the correct profile parameter in the URL

403 Forbidden

Cause: Token doesn't have access to the requested profile or resources

Solutions:

• Verify the token was generated for the correct profile
• Check that the profile name in the MCP URL matches the token's profile
• Ensure the profile has access to the MCP servers you're trying to use
• Confirm the profile exists and is active in your Civic account

Token not working in automation platform

Cause: Incorrect header format or URL configuration

Solutions:

• Double-check the Authorization header: Authorization: Bearer YOUR_TOKEN
• Verify the MCP URL includes both accountId and profile parameters
• Ensure Content-Type header is set: Content-Type: application/json
• Test the token with a simple curl command first to isolate the issue

How do I know when my token expires?

Answer: The expiration date is shown when you generate the token

Solutions:

• Set a calendar reminder when you generate the token
• Note the expiration date in your documentation
• Implement monitoring in your application to detect 401 errors
• Use shorter expiration periods for sensitive integrations

Comparison: Browser Auth vs Token Auth

Feature	Browser Authentication	Token Authentication
Best for	Desktop AI agents, interactive sessions	Background processes, autonomous agents, scheduled tasks
Setup	Click connect → browser opens → authorize	Generate token → copy to service
Token management	Automatic refresh	Manual generation (configurable up to 30 days)
Use cases	Claude Desktop, VS Code, Cursor	OpenAI Agent Builder, n8n, custom apps
Security	OAuth flow, automatic refresh	Manual rotation, environment variables
Expiration	Auto-refreshed	Configurable (up to 30 days), no auto-renewal

Next Steps

Installing into an agent

Learn about profile locking, skills, and other agent-specific configuration

Create your first toolkit

Set up a toolkit to organize your MCP servers before generating tokens

Manage authorizations

View your authorizations and connected services

OpenAI Agent setup

Complete guide to using Civic tokens with OpenAI Agent Builder