Users

User endpoints cover both self-service operations (viewing your own profile) and admin operations (managing all users). All operations are scoped to the current application — users in one application are completely invisible to another.

Self-Service

Self-service endpoints require a valid bearer token but no admin role.

GET/api/users/meBearer Token

Returns the current user's profile including roles.

Response

{
  "id": "user-uuid",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "picture": "https://avatars.githubusercontent.com/u/12345",
  "email_verified": true,
  "created_at": "2026-01-15T08:00:00Z",
  "updated_at": "2026-02-01T10:00:00Z",
  "roles": [
    {
      "id": "role-uuid",
      "name": "admin"
    }
  ]
}

GET/api/users/me/identitiesBearer Token

Returns all identity providers linked to the current user's account.

Response

{
  "identities": [
    {
      "id": "link-uuid",
      "provider_name": "github",
      "provider_user_id": "12345",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "created_at": "2026-01-15T08:00:00Z"
    }
  ]
}

GET/api/users/me/rolesBearer Token

Returns all roles assigned to the current user with their permissions.

Response

{
  "roles": [
    {
      "id": "role-uuid",
      "name": "admin",
      "description": "Full system access",
      "permissions": [
        {
          "id": "perm-uuid",
          "name": "users:read"
        },
        {
          "id": "perm-uuid",
          "name": "users:write"
        }
      ]
    }
  ]
}

Admin Operations

Admin endpoints require the admin role.

GET/api/usersAdmin

Returns a paginated list of all users. Supports search by email or name.

Parameter	Type	Description
page query	number	Page number (default: 1)
limit query	number	Results per page (default: 50, max: 100)
search query	string	Search by email or name

Response

{
  "users": [
    {
      "id": "user-uuid",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "picture": null,
      "email_verified": true,
      "created_at": "2026-01-15T08:00:00Z",
      "updated_at": "2026-02-01T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "total_pages": 1
  }
}

GET/api/users/:idAdmin

Returns a specific user's profile with their roles and linked identities.

Parameter	Type	Description
id* path	string	User ID

Response

{
  "id": "user-uuid",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "picture": null,
  "email_verified": true,
  "created_at": "2026-01-15T08:00:00Z",
  "updated_at": "2026-02-01T10:00:00Z",
  "roles": [
    {
      "id": "role-uuid",
      "name": "admin"
    }
  ],
  "identities": [
    {
      "id": "link-uuid",
      "provider_name": "github",
      "provider_user_id": "12345"
    }
  ]
}

PUT/api/users/:idAdmin

Updates a user's profile information.

Parameter	Type	Description
id* path	string	User ID
name body	string	Display name
email body	string	Email address
picture body	string	Profile picture URL

Request

{
  "name": "Jane Smith",
  "email": "jane.smith@example.com"
}

Response

{
  "message": "User updated"
}

DELETE/api/users/:idAdmin

Permanently deletes a user and all their associated data (sessions, identities, grants).

Parameter	Type	Description
id* path	string	User ID

Response

{
  "message": "User deleted"
}

GET/api/users/:id/sessionsAdmin

Returns all sessions (active and revoked) for a specific user.

Parameter	Type	Description
id* path	string	User ID

Response

{
  "sessions": [
    {
      "id": "session-uuid",
      "idp_name": "github",
      "ip_address": "203.0.113.1",
      "user_agent": "Mozilla/5.0...",
      "created_at": "2026-02-01T10:00:00Z",
      "expires_at": "2026-02-01T11:00:00Z",
      "last_active_at": "2026-02-01T10:30:00Z",
      "revoked_at": null
    }
  ]
}

DELETE/api/users/:id/sessionsAdmin

Revokes all active sessions for a specific user.

Parameter	Type	Description
id* path	string	User ID

Response

{
  "message": "All sessions revoked",
  "revoked_count": 2
}

DELETE/api/users/:id/identities/:linkIdAdmin

Removes a linked identity provider from a user's account.

Parameter	Type	Description
id* path	string	User ID
linkId* path	string	Identity link ID

Response

{
  "message": "Identity unlinked"
}

POST/api/users/:id/rolesAdmin

Assigns a role to a user.

Parameter	Type	Description
id* path	string	User ID
role_id* body	string	Role ID to assign

Request

{
  "role_id": "role-uuid"
}

Response

{
  "message": "Role assigned"
}

DELETE/api/users/:id/roles/:roleIdAdmin

Removes a role from a user.

Parameter	Type	Description
id* path	string	User ID
roleId* path	string	Role ID to remove

Response

{
  "message": "Role removed"
}