confused about the functionality of API tokens.

[hemachowdary-10]

can someone explain the clear functionality of the API Tokens. if possible with an real time example.

[crivetimihai]

Hi @hemachowdary-10, sorry for the confusion. I can add a short API token matrix (token purpose, expiration, scope, rotation) if you share which client path you are using (admin API vs direct proxy calls).

[crivetimihai]

Hi @hemachowdary-10, here's a clear explanation of API tokens in ContextForge.

What are API tokens?

API tokens are long-lived credentials for programmatic access. Instead of logging in with email/password each time, you create a token once and use it in your applications.

Real-world example — connecting Claude Desktop to ContextForge:

1. Log into the Admin UI with your email/password
2. Go to Tokens → Create Token
3. Give it a name (e.g., "My Claude Desktop Token"), optionally scope it to specific teams or servers
4. Copy the generated token — this is the only time you'll see the full token
5. Use it in your MCP client config:

{
  "mcpServers": {
    "my-gateway": {
      "url": "http://your-server:8080/servers/{id}/mcp",
      "headers": {
        "Authorization": "Bearer eyJhbGciOiJIUzI1NiI..."
      }
    }
  }
}

Token features:

Feature	Description
Team scoping	Restrict token to specific teams' tools/resources
Server scoping	Limit token to specific virtual servers only
IP restrictions	Only allow usage from specific IP addresses/CIDRs
Expiration	Set an expiry date for automatic revocation
Usage tracking	See when the token was last used (GET /tokens/{id}/usage)
Revocation	Immediately disable a token via DELETE /tokens/{id} or the UI

API endpoints:

• POST /tokens — Create a new API token
• GET /tokens — List your tokens
• GET /tokens/{id} — Token details
• PUT /tokens/{id} — Update token settings
• DELETE /tokens/{id} — Revoke a token
• GET /tokens/{id}/usage — Usage statistics

How tokens differ from session tokens:

• Session tokens are short-lived, created when you log into the UI, and expire after the session ends
• API tokens are long-lived, created explicitly, and persist until they expire or are revoked
• Both use JWT format with Authorization: Bearer <token> header

The token hash is stored securely in the database — the plaintext token is only shown once at creation time.