Skip to Content

Authentication

Identity and access management services.

⚠️ Breaking change in v0.7: OAuth scopes have been renamed from a2a.* to mcp:*. Backward compatibility is preserved during the transition window, but update your integrations now. See the scope migration guide.

OAuth 2.0 Authorization Code Flow

For third-party apps, browser-based clients, and mobile apps, use the OAuth 2.0 Authorization Code flow with PKCE. This is the recommended way to obtain access tokens on behalf of a user without handling their password.

→ See the OAuth 2.0 PKCE guide for the full implementation walkthrough.

Overview

Authentication in isA User is handled by four core services:

ServicePortPurpose
auth_service8201JWT tokens, API keys, device auth
account_service8202User profiles, settings
session_service8203Session tracking, context
authorization_service8204RBAC, permissions

Auth Service (8201)

JWT Authentication

curl -X POST "http://localhost:8201/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure_password"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Token Refresh

curl -X POST "http://localhost:8201/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'

API Key Management

curl -X POST "http://localhost:8201/api/v1/auth/api-keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App Key",
    "scopes": ["read:storage", "write:storage"],
    "expires_in_days": 365
  }'

Account Service (8202)

Create Account

curl -X POST "http://localhost:8202/api/v1/accounts" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "name": "John Doe",
    "password": "secure_password"
  }'

Get Profile

curl "http://localhost:8202/api/v1/accounts/me" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Update Profile

curl -X PATCH "http://localhost:8202/api/v1/accounts/me" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "preferences": {"theme": "dark"}
  }'

Session Service (8203)

Get Active Sessions

curl "http://localhost:8203/api/v1/sessions" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Revoke Session

curl -X DELETE "http://localhost:8203/api/v1/sessions/sess_abc123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Authorization Service (8204)

Check Permission

curl -X POST "http://localhost:8204/api/v1/authorization/check" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "storage",
    "action": "write",
    "resource_id": "file_123"
  }'

Built-in Roles

RoleDescription
ownerFull access, can delete resource
adminManage users and settings
editorRead and write access
viewerRead-only access
guestLimited temporary access

Security Features

Rate Limiting

EndpointLimit
Login5/minute
Token refresh10/minute
API calls1000/hour

Token Security

  • Access tokens expire in 1 hour
  • Refresh tokens expire in 30 days
  • Tokens are signed with RS256 or HS256
  • Device binding for sensitive operations

Python SDK

from isa_user import AuthClient, AccountClient
 
auth = AuthClient("http://localhost:8201")
account = AccountClient("http://localhost:8202")
 
# Login
tokens = await auth.login("user@example.com", "password")
 
# Get profile
profile = await account.get_profile(tokens.access_token)
 
# Create API key
api_key = await auth.create_api_key(
    token=tokens.access_token,
    name="My App",
    scopes=["read:storage"]
)

Next Steps

Home