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

identity-service design

Scope

identity-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/identity/auth/login
• POST /gateway/identity/users/list
• POST /gateway/identity/roles/list
• POST /gateway/identity/permissions/check

Gateway proxies them to identity-service:

• POST /identity/auth/login
• POST /identity/users/list
• POST /identity/roles/list
• POST /identity/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
• name
• description
• status: active | disabled
• audit fields
• version

auth_role_permission_binding

• id
• role_id
• permission
• scope_type
• scope_id
• 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 /identity/auth/login

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

Response:

{
  "success": true,
  "data": {
    "accessToken": "apt_xxx",
    "tokenType": "bearer",
    "expiresTime": "2026-04-28T07:10:00Z",
    "user": {
      "id": "user-id",
      "username": "demo-user",
      "displayName": "Demo User",
      "email": "demo@example.com",
      "metadata": {},
      "lastLoginTime": "2026-04-27T23:10:00Z",
      "createdTime": "2026-04-27T23:00:00Z",
      "updatedTime": "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 /identity/auth/tokens/verify

{
  "accessToken": "apt_xxx"
}

Response:

{
  "success": true,
  "data": {
    "active": true,
    "userId": "user-id",
    "username": "demo-user",
    "expiresTime": "2026-04-28T07:10:00"
  }
}

Permission Check

POST /identity/permissions/check

{
  "userId": "user-id",
  "permission": "workflow:read",
  "scopeType": null,
  "scopeId": null
}

Response:

{
  "success": true,
  "data": {
    "allowed": true,
    "reason": "matched",
    "matchedRoleIds": ["role-id"]
  }
}

Migration

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