Civic Tokens

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

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 Nexus MCP servers from external services. They are:

Profile-scoped: Each token is tied to a specific Civic Nexus profile (toolkit)
Time-limited: Tokens expire after 30 days
Revocable: You can revoke tokens at any time from your account settings
Secure: Tokens use industry-standard OAuth 2.0 token exchange (RFC 8693)

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

Navigate to Install page

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

Choose MCP URL as your agent type

In the Guided section, select MCP URL to see authentication options

Select token authentication

Under Step 2: Choose authentication method, select Generate a Civic token

Generate the token

Click the Generate token button to open the token creation modal

Token expiration

Tokens are valid for 30 days from generation. The expiration date will be displayed when you create the token.

Copy and store securely

After clicking Generate, copy the token immediately and store it securely

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 Nexus tools:

Create your agent

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

Add MCP server

Under Tools & Integrations, add a new MCP server connection

Configure the connection

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

Test the connection

Save and test that your agent can access the Nexus tools

URL parameters:

accountId - Your Civic account ID
profile - The profile name (toolkit) that determines which MCP servers the agent can access

Use the profile alias you created in Nexus.

n8n Workflows

To use Civic Nexus in your n8n automations:

Add HTTP Request node

In your n8n workflow, add an HTTP Request node

Configure authentication

URL: https://nexus.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

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://nexus.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
JavaScript
Python

curl 'https://nexus.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"
  }'

Token Expiration & Renewal

Expiration

Tokens expire 30 days after generation
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:

Generate a new token

Follow the token generation steps above

Update your service

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

Old token invalidated

The expired token is automatically invalidated

Best Practice: Set calendar reminders a few days before token expiration to avoid service interruption.

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 are valid for 30 days
Set reminders to rotate tokens before they expire
Generate new tokens proactively to avoid service interruption
Consider your 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

Revoke unused tokens

Remove tokens from the Authorizations page when no longer needed

Monitor token usage

Check the Activity page for unexpected usage patterns

Troubleshooting

401 Unauthorized

Cause: Token is expired, invalid, or incorrectly formattedSolutions:

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 resourcesSolutions:

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 Nexus account

Token not working in automation platform

Cause: Incorrect header format or URL configurationSolutions:

Double-check the Authorization header: Authorization: Bearer YOUR_TOKEN
Verify the MCP URL includes the profile parameter: ?profile=YOUR_PROFILE_NAME
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: Civic doesn’t send expiration warningsSolutions:

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
Consider shorter expiration periods with more frequent rotation

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 every 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	30 days, no auto-renewal
Revocation	Immediate via authorization page	Immediate via authorization page

Next Steps

Create Your First Profile

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

Manage Authorizations

View and revoke tokens from your authorization dashboard

OpenAI Agent Setup

Complete guide to using Civic tokens with OpenAI Agent Builder

Security Guide

Learn more about Nexus security and best practices

Getting Started

Supported Clients

Developers

Reference

AI Prompts

Support

​Civic Tokens

​What are Civic Tokens?

​When to Use Tokens vs Browser Auth

​Use Browser Authentication

Desktop AI Agents

Interactive Sessions

​Use Token Authentication

Agent Builders

Automation Platforms

Custom Applications

Restricted Environments

​How to Generate a Token

​Using Tokens in Different Services

​OpenAI Agent Builder

​n8n Workflows

​Other Automation Platforms

​Custom Applications

​Token Expiration & Renewal

​Expiration

​Renewal

​Security Best Practices

​Storage

​Access Control

One token per service

Use appropriate profiles

Revoke unused tokens

Monitor token usage

​Troubleshooting

​Comparison: Browser Auth vs Token Auth

​Next Steps

Create Your First Profile

Manage Authorizations

OpenAI Agent Setup

Security Guide

Civic Tokens

What are Civic Tokens?

When to Use Tokens vs Browser Auth

Use Browser Authentication

Use Token Authentication

How to Generate a Token

Using Tokens in Different Services

OpenAI Agent Builder

n8n Workflows

Other Automation Platforms

Custom Applications

Token Expiration & Renewal

Expiration

Renewal

Security Best Practices

Storage

Access Control

Troubleshooting

Comparison: Browser Auth vs Token Auth

Next Steps