# 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:

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

Runtime setting:

```powershell
$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`

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

Response:

```json
{
  "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`

```json
{
  "accessToken": "apt_xxx"
}
```

Response:

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

## Permission Check

`POST /identity/permissions/check`

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

Response:

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

## Migration

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