# Users (admin) API

Source: https://frameleaf.app/docs/api/reference/users-admin/

Use your own server and its scoped API keys.

## List backup device metadata across users

GET /api/admin/backup-devices

Administrative metadata only. No reconciliation digests or foreign asset access. quietForDays is elapsed whole days since reported successful backup, null when never reported.

```json
{
  "description": "Administrative metadata only. No reconciliation digests or foreign asset access. quietForDays is elapsed whole days since reported successful backup, null when never reported.",
  "operationId": "listAllBackupDevices",
  "parameters": [
    {
      "name": "limit",
      "required": false,
      "in": "query",
      "schema": {
        "minimum": 1,
        "maximum": 200,
        "default": 100,
        "type": "integer"
      }
    },
    {
      "name": "offset",
      "required": false,
      "in": "query",
      "schema": {
        "minimum": 0,
        "maximum": 1000000,
        "default": 0,
        "type": "integer"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/BackupDeviceListDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "List backup device metadata across users",
  "tags": [
    "Users (admin)"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "adminUser.read"
}
```

## Retrieve calendar heatmap activity

GET /api/admin/users/{id}/calendar-heatmap

Retrieve activity counts for a specified period, in a calendar heatmap format.

```json
{
  "description": "Retrieve activity counts for a specified period, in a calendar heatmap format.",
  "operationId": "getUserCalendarHeatmapAdmin",
  "parameters": [
    {
      "name": "from",
      "required": false,
      "in": "query",
      "description": "Start date in UTC",
      "schema": {
        "format": "date",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
        "example": "2024-01-01",
        "type": "string"
      }
    },
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "to",
      "required": false,
      "in": "query",
      "description": "End date in UTC",
      "schema": {
        "format": "date",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
        "example": "2024-01-01",
        "type": "string"
      }
    },
    {
      "name": "type",
      "required": false,
      "in": "query",
      "schema": {
        "default": "Upload",
        "$ref": "#/components/schemas/CalendarHeatmapType"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CalendarHeatmapResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve calendar heatmap activity",
  "tags": [
    "Users (admin)"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "adminUser.read"
}
```

## Retrieve whether a user has a PIN

GET /api/admin/users/{id}/pin-code

Retrieve whether a specific user has a PIN code set, never the PIN itself.

```json
{
  "description": "Retrieve whether a specific user has a PIN code set, never the PIN itself.",
  "operationId": "getUserPinCodeStateAdmin",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UserAdminPinCodeStateResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve whether a user has a PIN",
  "tags": [
    "Users (admin)"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "adminUser.read"
}
```

## Retrieve user preferences

GET /api/admin/users/{id}/preferences

Retrieve the preferences of a specific user.

```json
{
  "description": "Retrieve the preferences of a specific user.",
  "operationId": "getUserPreferencesAdmin",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UserPreferencesResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve user preferences",
  "tags": [
    "Users (admin)"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "adminUser.read"
}
```

## Update user preferences

PUT /api/admin/users/{id}/preferences

Update the preferences of a specific user.

```json
{
  "deprecated": true,
  "description": "Update the preferences of a specific user.",
  "operationId": "updateUserPreferencesAdmin",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UserPreferencesUpdateDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UserPreferencesResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Update user preferences",
  "tags": [
    "Users (admin)",
    "Deprecated"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "adminUser.update"
}
```

## Retrieve user sessions

GET /api/admin/users/{id}/sessions

Retrieve all sessions for a specific user.

```json
{
  "description": "Retrieve all sessions for a specific user.",
  "operationId": "getUserSessionsAdmin",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/SessionResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve user sessions",
  "tags": [
    "Users (admin)"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "adminSession.read"
}
```

## `SessionService.delete` only checks `Permission.AuthDeviceDelete` over the caller's
own sessions, so an administrator could never revoke a foreign session through it. This is
the explicit, audited admin path the account detail's Security tab needs instead.

DELETE /api/admin/users/{id}/sessions/{sessionId}

Delete a specific session for a specific user, signing that device out.

```json
{
  "description": "Delete a specific session for a specific user, signing that device out.",
  "operationId": "deleteUserSessionAdmin",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "sessionId",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "`SessionService.delete` only checks `Permission.AuthDeviceDelete` over the caller's\nown sessions, so an administrator could never revoke a foreign session through it. This is\nthe explicit, audited admin path the account detail's Security tab needs instead.",
  "tags": [
    "Users (admin)"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "adminSession.delete"
}
```

## Retrieve user statistics

GET /api/admin/users/{id}/statistics

Retrieve asset statistics for a specific user.

```json
{
  "description": "Retrieve asset statistics for a specific user.",
  "operationId": "getUserStatisticsAdmin",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "isFavorite",
      "required": false,
      "in": "query",
      "description": "Filter by favorite status",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "isTrashed",
      "required": false,
      "in": "query",
      "description": "Filter by trash status",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "visibility",
      "required": false,
      "in": "query",
      "schema": {
        "$ref": "#/components/schemas/AssetVisibility"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AssetStatsResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve user statistics",
  "tags": [
    "Users (admin)"
  ],
  "x-frameleaf-admin-only": true,
  "x-frameleaf-permission": "adminUser.read"
}
```