OAuth 2.0 Authentication

OAuth 2.0 Bearer tokens provide user identity linking — allowing agents to check rewards, earn cashback, and personalize results for specific users.

Dual Auth Model

Resonance supports two auth methods that can be used together:

Method	Purpose	Header
HMAC-SHA256	Agent/brand identity (who is calling)	X-RSNC-Agent-Key, X-RSNC-Timestamp, X-RSNC-Signature
OAuth 2.0	User identity (on whose behalf)	Authorization: Bearer <token>

When to use each

• HMAC only — Brand management tools (analytics, program management)
• OAuth only — User-facing queries (check balance without agent key)
• Both — Personalized commerce (agent routes purchases for a specific user)

Token Format

Resonance validates HS256 JWTs (compatible with Supabase Auth):

{
  "sub": "user-uuid-or-email",
  "email": "[email protected]",
  "aud": "rsnc-agent",
  "iss": "https://your-auth-provider.com",
  "exp": 1709510400,
  "iat": 1709506800
}

Required Claims

Claim	Description
sub	User identifier (UUID or email). Becomes auth.userId in tool handlers.
exp	Expiration timestamp. Tokens past expiry are rejected.

Optional Claims

Claim	Description
email	User email address
aud	Expected audience (validated if OAUTH_AUDIENCE is configured)
iss	Token issuer (validated if OAUTH_ISSUER_URL is configured)

Usage

With HMAC (Dual Auth)

curl -X POST https://agent.rsnc.network/tasks/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <user-jwt>" \
  -H "X-RSNC-Agent-Key: your-key-id" \
  -H "X-RSNC-Timestamp: $(date +%s)" \
  -H "X-RSNC-Signature: <computed-signature>" \
  -d '{
    "message": {
      "role": "user",
      "parts": [{
        "type": "data",
        "mimeType": "application/json",
        "data": {
          "skill": "check_rewards",
          "brandId": "0xBrandAddress"
        }
      }]
    }
  }'

OAuth Only

curl -X POST https://agent.rsnc.network/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <user-jwt>" \
  -d '...'

Note: OAuth alone does not satisfy HMAC requirements. Tools that require HMAC auth will still reject OAuth-only requests. OAuth provides the userId for personalization.

Configuration

Environment variables for JWT validation:

Variable	Description	Required
SUPABASE_SECRET_KEY	JWT signing secret (HS256)	Yes
OAUTH_ISSUER_URL	Expected iss claim value	No
OAUTH_AUDIENCE	Expected aud claim value	No