Security in AI Connect — Token Lifecycle, Permissions, Best Practices

Core Principles

AI Connect implements the Servio Protocol security model, built around 4 core principles:

1. Least privilege — Every token operates under the permissions of the user who created it. No more.
2. Standards-based — OAuth 2.0 + PKCE (S256), not homegrown mechanisms.
3. Auditable — Every request is recorded in last_used_at + IP + User Agent.
4. Revocable — Immediate cancellation via UI. No “grace period”.

OAuth 2.0 + PKCE — Why It Matters

The problem we solve: An AI agent requests permission to access your site. How do you verify it’s actually the agent you know and not an attacker?

PKCE (Proof Key for Code Exchange):

1. The agent generates a random code_verifier (43-128 chars).
2. The agent computes code_challenge = SHA256(code_verifier) — sends only the challenge.
3. You approve in the browser → the agent receives an authorization_code.
4. The agent sends code + code_verifier → the server verifies SHA256(verifier) === challenge.
5. If it matches → returns an access_token.

Result: Even if an attacker intercepts the authorization_code in transit (MITM) — they cannot use it without the original code_verifier.

Servio Protocol RULE-009 requires PKCE with S256 — plain or other methods are not accepted.

Token Lifecycle

Access Token

• Duration: 1-24 hours (RULE-010)
• Usage: Bearer token in every request — Authorization: Bearer xfa_...
• Format: xfa_ + 64 hex characters (or platform-specific prefix)
• Customisation: Each platform sets its own duration in config

Refresh Token

• Duration: 7-90 days (RULE-011)
• Usage: Only for refreshing access_token via POST /oauth/token
• Format: xfr_ + 64 hex characters
• Exception: Shopify doesn’t support refresh_token — uses a 30-day Single MCP Token

Cascade Revoke

When a user clicks Revoke on the My Tokens page:

1. access_token marked as revoked (immediate).
2. The linked refresh_token is also marked as revoked (required!).
3. Tokens are not deleted — kept for audit trail.

Important: Revoke both sides (access + refresh) together. Otherwise an attacker with the refresh_token can refresh the access.

Scopes — What Can Each Token Do?

The Servio Protocol currently defines these access scopes:

Scope	Description	Typically included in
read	Read content	Free tier
write	Create / update	Pro tier
delete	Delete	Pro tier (advanced)
admin	Admin actions	Admin Pro tools

This list is not fixed — individual plugins (current or future) may define additional scopes for platform-specific capabilities.

Important: A scope is the upper bound of what a token can do — it never grants more than the underlying user already has on the platform. Scope is the ceiling; the user’s own permissions are the floor.

Permissions Model — Two Layers

Layer 1: Token Scopes

Defined in the token. Cannot be exceeded.

Layer 2: User Permissions

Defined in the platform itself (WordPress roles, Moodle capabilities, XenForo permissions).

Effective permission formula:

allowed_actions = token_scopes ∩ user_permissions

Example:

• Token with write scope
• User is an “Author” in WordPress (can only publish their own posts)
• The agent calls wordpress.createPost — works
• The agent calls wordpress.updatePost on someone else’s post — WordPress refuses

Rate Limiting

Servio Protocol RULE-012 requires rate limiting on every authenticated endpoint.

Mechanism

Default limits (configurable per plugin, via the plugin’s own settings):

• 50 requests / minute / token (default)
• 1,000 requests / hour / token

Response on Exceed

{
  "error": "rate_limit_exceeded",
  "retry_after": 42,
  "limit": 60,
  "window": "minute"
}

HTTP status: 429 Too Many Requests.

Malicious Bypass

Attempting to use IP rotation to bypass rate limiting → the token is sent to automatic revoke. No bypass available.

Audit Trail

Every token stores:

• last_used_at — exact timestamp
• last_used_ip — IP of the most recent request
• last_used_ua — User-Agent (client identifier)
• usage_count — total requests since creation
• first_used_at — timestamp of first use

The My Tokens page displays all these fields with full transparency.

Best Practices for Production Deployment

1. HTTPS Required

• No OAuth PKCE without HTTPS. Browsers will block the token.
• Let’s Encrypt is free and sufficient — no excuse.

2. Set Strict Rate Limits

• For small sites, the default 50/minute is usually enough.
• Adjust the limits in the plugin’s own settings if you need more or less.
• For a one-off heavy job (for example, a bulk import): create a dedicated token and revoke it afterwards.

3. Isolate the MCP Subdomain

• mcp.example.com instead of example.com/api/aiconnect-*
• Isolates MCP traffic from regular web traffic
• Enables CDN caching of the manifest only

4. Monitor last_used_at

• Tokens unused for 30+ days → run bulk revoke
• Set up cron: 0 3 * * * to run cleanup lazy tasks

5. Rotation Policy

• Recommended: rotate tokens periodically (for example, every 30-90 days) — revoke and generate new ones.
• Automation: a cron job that generates a new token and updates the agent.

6. Never Commit Tokens

• Verify .env is in .gitignore
• Pre-commit hook: git-secrets or gitleaks — scans for tokens
• Rotate immediately if a token was exposed

Threat Model — What AI Connect Doesn’t Protect Against

• Compromised platform — If the admin account is breached, tokens can be regenerated. AI Connect relies on the platform’s own security.
• Compromised AI client — If your machine is breached and the AI client is stolen, the tokens can be used maliciously. Recommended: full-disk encryption + a password on the client.
• Man-in-the-middle without HTTPS — HTTPS is required. Otherwise the token can be exposed.
• Session hijack in the OAuth flow — PKCE protects against this, but only if the AI client implements PKCE correctly.

Cases to Report Immediately

If you suspect a token was stolen:

1. Revoke immediately — on the My Tokens page.
2. Check the audit log — last_used_ip — is the IP familiar?
3. Rotate all tokens — not just the suspect one.
4. Contact support — contact us.
5. Check whether a write/delete tool published suspicious content — if so, restore from backup.

Privacy (GDPR)

• PII flows — some tools may return personal data (for example, customer-facing tools on e-commerce platforms). If your agent processes personal data, put a Data Processing Agreement (DPA) in place.
• Right to erasure — Clicking “Delete all my tokens” removes all the user’s tokens and clears the last_used_* fields.
• Data retention — Audit/usage data is retained according to each plugin’s configuration; check your specific plugin’s settings.