Authentication

Sign in through the browser connector

In Claude, ChatGPT, Le Chat, or Perplexity, add ~alter as a custom connector at https://mcp.truealter.com, sign in through your browser, and choose your ~handle. Choosing your ~handle is how your account is created. Then use your AI as you normally would.

Sign-in runs over OAuth. The connector registers itself and discovers the sign-in endpoints, so your client walks you through consent and stores the capability token for you. There is no token to copy, and there is no member website to log in to. Your AI client is the surface. The JWT, capability-token, and curl methods below are for building your own programmatic client.

JWT Bearer Tokens

Most API endpoints require a JWT access token obtained via the /auth/login endpoint. Access tokens expire after 6 hours. Refresh tokens are set as HttpOnly cookies with 7-day expiry.

Authorization: Bearer <access_token>

curl -X POST https://mcp.truealter.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-secure-password", // pragma: allowlist secret
    "full_name": "Jane Smith"
  }'

# 201 Created
# {
#   "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
#   "email": "you@example.com",
#   "full_name": "Jane Smith",
#   "role": "member"
# }

curl -X POST https://mcp.truealter.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-secure-password"}'

# 200 OK
# {
#   "access_token": "eyJhbGciOiJFUzI1NiIs...",
#   "token_type": "bearer"
# }
# Set-Cookie: refresh_token=...; HttpOnly; Secure; SameSite=Lax; Max-Age=604800

# The refresh token cookie must be included in the request
curl -X POST https://mcp.truealter.com/api/v1/auth/refresh \
  -b "refresh_token=your_refresh_token_value"

# 200 OK
# {
#   "access_token": "eyJhbGciOiJFUzI1NiIs...(new)...",
#   "token_type": "bearer"
# }
# Set-Cookie: refresh_token=...(new)...; HttpOnly; Secure; SameSite=Lax

OAuth-bearer capability authentication

Agents and programmatic clients authenticate through the OAuth-bearer capability ladder. Connect via OAuth, then receive a capability token (cap-JWT) scoped per tool with explicit consent. The token travels in the Authorization header as a bearer credential. Rate limits are set per authenticated role, not by a free/pro split: a member capability allows 120 requests/minute and 5,000/day, while unauthenticated requests run in the lowest bucket at 40/minute and 20,000/day.

Authorization: Bearer <capability_token>

curl https://mcp.truealter.com/api/v1/me \
  -H "Authorization: Bearer eyJhbGciOiJFUzI1NiIs..."

Multi-Factor Authentication (TOTP)

~alter supports TOTP-based multi-factor authentication as an optional second factor. Once enabled, login requires both credentials and a 6-digit code from an authenticator app.

# Step 1: Request TOTP secret
curl -X POST https://mcp.truealter.com/api/v1/auth/mfa/setup \
  -H "Authorization: Bearer eyJhbGciOiJFUzI1NiIs..."

# 200 OK
# {
#   "secret": "JBSWY3DPEHPK3PXP", // pragma: allowlist secret
#   "provisioning_uri": "otpauth://totp/~Alter:you@example.com?secret=JBSWY3DPEHPK3PXP&issuer=~Alter"
# }

# Step 2: Verify with a code from your authenticator app
curl -X POST https://mcp.truealter.com/api/v1/auth/mfa/verify \
  -H "Authorization: Bearer eyJhbGciOiJFUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

# 200 OK
# { "mfa_enabled": true }

// Initial login response when MFA is enabled
{
  "mfa_required": true,
  "mfa_token": "temp_mfa_abc123..."
}

// Complete MFA
POST /auth/mfa/challenge
{
  "mfa_token": "temp_mfa_abc123...",
  "code": "123456"
}

// Returns the normal token response
{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "token_type": "bearer"
}

Collective single sign-on

Collective accounts can federate sign-on with their own identity provider. This is configured at the collective level, outside the agent-facing surface documented here. SSO-authenticated users receive the same JWT access tokens as password-authenticated users, so every call below works identically. Collective admins can reach support@truealter.com to set it up.

x402 Micropayment Authentication

Paid MCP tools and credential queries require x402 payment proof. Include a _payment object in the tool arguments with a valid payment receipt. x402 carries payment only: the call still authenticates via OAuth-bearer or login. 75% of each payment accrues to the data subject; indicative only, server-authoritative at settlement.

// x402 payment in MCP tool arguments
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "query_trait_profile",
    "arguments": {
      "member_id": "a1b2c3d4-...",
      "_payment": {
        "protocol": "x402",
        "amount": "0.20",
        "currency": "USD",
        "receipt": "x402_receipt_abc123..."
      }
    }
  }
}

When a paid tool is called without payment, the server returns HTTP 402 Payment Required (or JSON-RPC error code -32000) with pricing metadata. See the Error Reference for details.

Next Steps