ProxyToken Authentication
For cross-instance requests, ProxyTokens authenticate the requesting instance.
ProxyToken Structure
{
"iss": "alice.example.com", // Requesting instance
"aud": "bob.example.com", // Target instance
"sub": "alice.example.com", // User identity
"exp": 1738400000, // Short-lived (5-60 min)
"iat": 1738396800,
"action": "read_file", // Requested operation
"resource": "f1~abc123...", // Resource identifier
"k": "20250205" // Signing key ID
}Creation
Algorithm: Create ProxyToken
Input: requester id_tag, target_instance, action, resource
Output: JWT token string
1. Retrieve latest signing key:
- Query latest key_id for tenant
- Load private key from AuthAdapter
2. Build JWT claims:
- iss: Requester's id_tag
- aud: Target instance domain
- sub: Requester's id_tag
- exp: Current time + 30 minutes
- iat: Current time
- action: Requested operation
- resource: Resource identifier
- k: Key ID used for signing
3. Sign JWT using ES384 algorithm:
- Use private key
- Standard JWT encoding
4. Return base64-encoded JWTValidation
Algorithm: Validate ProxyToken
Input: JWT token string
Output: Result<ProxyTokenClaims>
1. Decode JWT without signature verification (read claims)
2. Extract issuer and key_id from unverified claims
3. Fetch issuer's profile from remote instance
4. Look up public key by key_id in profile
5. Verify JWT signature using issuer's public key (ES384)
6. Check expiration timestamp:
- If exp < current_time: Return TokenExpired error
7. Check audience claim:
- If aud != this_instance.base_id_tag: Return InvalidAudience error
8. Return verified claims
Validation ensures:
- Token signed by claimed issuer
- Token not expired
- Token intended for this instanceUse Cases
ProxyTokens are used for:
- File fetching: Downloading attachments from remote instances
- Profile queries: Accessing extended profile information
- Database sync: Read access to federated databases
See Also
- Key Verification - How keys are cached and verified
- Data Synchronization - File and profile sync
- Access Control - Authorization