agent-platform/docs/auth-service-design.md

auth-service design

Scope

auth-service owns Web Studio account/password login, users, roles, role assignments, and permission checks.

The auth domain is single-workspace. Auth API payloads and auth tables do not carry workspace partition fields.

Frontend Contract

Frontend requests go through /gateway:

• POST /gateway/auth/login
• GET /gateway/auth/users
• GET /gateway/auth/roles
• POST /gateway/auth/permissions/check

Gateway proxies them to auth-service:

• POST /auth/login
• GET /auth/users
• GET /auth/roles
• POST /auth/permissions/check

After login, frontend sends:

• Authorization: Bearer ...
• x-user-id

Database

PostgreSQL:

postgresql+psycopg://admin:hFOvG5UBeK5KIGhz5cQH@git.newpoint.work:5432/vectordb

Runtime setting:

$env:AGENT_PLATFORM_DATABASE_URL="postgresql+psycopg://admin:hFOvG5UBeK5KIGhz5cQH@git.newpoint.work:5432/vectordb"

Tables

auth_user

• id
• username
• password_hash
• display_name
• email
• status: active | disabled | deleted
• metadata_json
• last_login_time
• audit fields
• version

auth_role

• id
• code
• name
• description
• status: active | disabled
• permissions_json
• audit fields
• version

auth_role_assignment

• id
• user_id
• role_id
• status: active | revoked
• scope_type
• scope_id
• expires_time
• audit fields
• version

Login

POST /auth/login

{
  "username": "demo-user",
  "password": "demo-password"
}

Response:

{
  "access_token": "apt_xxx",
  "token_type": "bearer",
  "expires_time": "2026-04-28T07:10:00Z",
  "user": {
    "id": "user-id",
    "username": "demo-user",
    "display_name": "Demo User",
    "email": "demo@example.com",
    "status": "active",
    "metadata_json": {},
    "last_login_time": "2026-04-27T23:10:00Z",
    "created_time": "2026-04-27T23:00:00Z"
  }
}

Passwords are stored with salted PBKDF2-HMAC-SHA256. Access tokens are HMAC signed with AGENT_PLATFORM_CREDENTIAL_ENCRYPTION_KEY.

Token Verification

POST /auth/tokens/verify

{
  "access_token": "apt_xxx"
}

Response:

{
  "active": true,
  "user_id": "user-id",
  "username": "demo-user",
  "expires_time": "2026-04-28T07:10:00"
}

Permission Check

POST /auth/permissions/check

{
  "user_id": "user-id",
  "permission": "workflow:read",
  "scope_type": null,
  "scope_id": null
}

Response:

{
  "allowed": true,
  "reason": "matched",
  "matched_role_ids": ["role-id"]
}

Migration

cd services/auth-service
$env:AGENT_PLATFORM_DATABASE_URL="postgresql+psycopg://admin:hFOvG5UBeK5KIGhz5cQH@git.newpoint.work:5432/vectordb"
alembic upgrade head