Admin

All admin endpoints require admin authentication. Requests from non-admin users will be rejected with a 403 Forbidden error.

Authorization

string

required

Bearer token (JWT or API token) for admin user

Get System Stats

Retrieve system statistics and analytics.

curl -X GET http://localhost:3001/api/admin/stats \
  -H "Authorization: Bearer ADMIN_TOKEN"

{
  "users": {
    "total": 42,
    "active": 38,
    "pending": 4,
    "admins": 2
  },
  "notes": {
    "total": 1523,
    "active": 1450,
    "trashed": 73,
    "archived": 245
  },
  "tags": {
    "total": 156,
    "active": 148
  },
  "shares": {
    "total": 89,
    "active": 82
  }
}

List Users

Retrieve all users with pagination.

curl -X GET "http://localhost:3001/api/admin/users" \
  -H "Authorization: Bearer ADMIN_TOKEN"

skip

number

default:0

Number of users to skip (for pagination)

take

number

default:50

Number of users to return (max 100)

{
  "users": [
    {
      "id": "user-uuid-1",
      "email": "admin@example.com",
      "name": "Admin User",
      "profileImage": null,
      "isAdmin": true,
      "status": "active",
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:00:00.000Z"
    },
    {
      "id": "user-uuid-2",
      "email": "user@example.com",
      "name": "Regular User",
      "profileImage": "/uploads/profiles/user-uuid-2.jpg",
      "isAdmin": false,
      "status": "active",
      "createdAt": "2026-02-01T14:30:00.000Z",
      "updatedAt": "2026-03-01T09:15:00.000Z"
    }
  ],
  "total": 42,
  "skip": 0,
  "take": 50
}

users

array

Array of user objects

total

number

Total number of users in the system

skip

number

Number of users skipped (pagination offset)

take

number

Number of users returned

List Pending Users

Retrieve all users with pending status (awaiting approval).

curl -X GET http://localhost:3001/api/admin/users/pending \
  -H "Authorization: Bearer ADMIN_TOKEN"

[
  {
    "id": "user-uuid-3",
    "email": "pending@example.com",
    "name": "Pending User",
    "profileImage": null,
    "isAdmin": false,
    "status": "pending",
    "createdAt": "2026-03-02T10:30:00.000Z",
    "updatedAt": "2026-03-02T10:30:00.000Z"
  }
]

Create User

Create a new user account (admin-initiated).

curl -X POST http://localhost:3001/api/admin/users \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "securepassword123",
    "name": "New User"
  }'

string

required

Valid email address (must be unique)

password

string

required

Password (minimum 8 characters)

name

string

required

User’s display name (max 100 characters, whitespace trimmed)

{
  "id": "user-uuid-new",
  "email": "newuser@example.com",
  "name": "New User",
  "profileImage": null,
  "isAdmin": false,
  "status": "active",
  "createdAt": "2026-03-02T11:00:00.000Z",
  "updatedAt": "2026-03-02T11:00:00.000Z"
}

Admin-created users are always set to active status regardless of registration mode.

Error Responses

409 Conflict

{
  "statusCode": 409,
  "message": "User already exists",
  "error": "Conflict"
}

Update User

Update user details including admin status.

curl -X PATCH http://localhost:3001/api/admin/users/user-uuid-2 \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "updated@example.com",
    "name": "Updated Name",
    "isAdmin": true
  }'

string

required

User UUID to update

string

Updated email address (must be unique)

name

string

Updated display name

isAdmin

boolean

Grant or revoke admin privileges

{
  "id": "user-uuid-2",
  "email": "updated@example.com",
  "name": "Updated Name",
  "profileImage": "/uploads/profiles/user-uuid-2.jpg",
  "isAdmin": true,
  "status": "active",
  "createdAt": "2026-02-01T14:30:00.000Z",
  "updatedAt": "2026-03-02T11:30:00.000Z"
}

Admins cannot demote themselves. If you attempt to set isAdmin: false on your own account, the request will be rejected.

Error Responses

403 Forbidden

{
  "statusCode": 403,
  "message": "Cannot modify your own admin status",
  "error": "Forbidden"
}

Delete User

Permanently delete a user and all associated data.

curl -X DELETE http://localhost:3001/api/admin/users/user-uuid-2 \
  -H "Authorization: Bearer ADMIN_TOKEN"

string

required

User UUID to delete

{
  "message": "User deleted successfully"
}

Deleting a user is irreversible and will:

Delete all notes owned by the user
Delete all tags created by the user
Delete all shares created by or shared to the user
Revoke all refresh tokens
Remove profile image from filesystem

Reset User Password

Reset a user’s password (admin-initiated password reset).

curl -X POST http://localhost:3001/api/admin/users/user-uuid-2/reset-password \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "newPassword": "newpassword123"
  }'

string

required

User UUID

newPassword

string

New password (minimum 8 characters, optional)

{
  "message": "Password reset successfully",
  "temporaryPassword": "Xyz789Abc123"
}

If newPassword is not provided, a random temporary password is generated and returned in the response.

Approve User

Approve a pending user account.

curl -X POST http://localhost:3001/api/admin/users/user-uuid-3/approve \
  -H "Authorization: Bearer ADMIN_TOKEN"

string

required

User UUID to approve

{
  "id": "user-uuid-3",
  "email": "pending@example.com",
  "name": "Pending User",
  "profileImage": null,
  "isAdmin": false,
  "status": "active",
  "createdAt": "2026-03-02T10:30:00.000Z",
  "updatedAt": "2026-03-02T12:00:00.000Z"
}

After approval, the user can log in and receive authentication tokens.

Reject User

Reject and delete a pending user account.

curl -X POST http://localhost:3001/api/admin/users/user-uuid-3/reject \
  -H "Authorization: Bearer ADMIN_TOKEN"

string

required

User UUID to reject

{
  "message": "User rejected and deleted"
}

Rejecting a user permanently deletes their account. This action cannot be undone.

Registration Settings

Get Registration Mode

curl -X GET http://localhost:3001/api/admin/settings/registration \
  -H "Authorization: Bearer ADMIN_TOKEN"

{
  "mode": "enabled"
}

mode

enum

Registration mode:

disabled - No new registrations allowed
enabled - Open registration, users are active immediately
review - Users can register but require admin approval

Update Registration Mode

curl -X PATCH http://localhost:3001/api/admin/settings/registration \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "review"
  }'

mode

enum

required

New registration mode:

disabled - Close registration
enabled - Open registration
review - Require admin approval

{
  "mode": "review"
}

If the USER_SIGNUP environment variable is set, it overrides the database setting and cannot be changed via the API.

OIDC Settings

Get OIDC Configuration

curl -X GET http://localhost:3001/api/admin/settings/oidc \
  -H "Authorization: Bearer ADMIN_TOKEN"

{
  "enabled": true,
  "providerName": "Pocket ID",
  "issuerUrl": "https://auth.example.com",
  "clientId": "anchor-client-id",
  "clientSecretSet": true,
  "disableInternalAuth": false
}

enabled

boolean

Whether OIDC authentication is enabled

providerName

string

Display name for OIDC provider

issuerUrl

string

OIDC issuer URL (well-known endpoint base)

clientId

string

OIDC client ID

clientSecretSet

boolean

Whether client secret is configured (actual secret never returned)

disableInternalAuth

boolean

Whether password-based authentication is disabled

Update OIDC Configuration

curl -X PATCH http://localhost:3001/api/admin/settings/oidc \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "providerName": "Pocket ID",
    "issuerUrl": "https://auth.example.com",
    "clientId": "anchor-client-id",
    "clientSecret": "secret-value",
    "disableInternalAuth": false
  }'

enabled

boolean

Enable or disable OIDC authentication

providerName

string

Display name for the OIDC provider

issuerUrl

string

OIDC issuer URL (must be valid URL)

clientId

string

OIDC client ID

clientSecret

string

OIDC client secret (optional for public clients using PKCE)

clearClientSecret

boolean

Set to true to remove the stored client secret

disableInternalAuth

boolean

Disable password-based authentication when OIDC is enabled

{
  "enabled": true,
  "providerName": "Pocket ID",
  "issuerUrl": "https://auth.example.com",
  "clientId": "anchor-client-id",
  "clientSecretSet": true,
  "disableInternalAuth": false
}

If disableInternalAuth is set to true, users without OIDC accounts will not be able to log in using email/password.

Environment variables (OIDC_* and DISABLE_INTERNAL_AUTH) override database settings. Changes via API only affect database-stored values.

Admin Guard

All admin endpoints are protected by the AdminGuard:

Requires valid authentication (JWT or API token)
Requires isAdmin: true on user account
Returns 403 Forbidden for non-admin users

403 Forbidden

{
  "statusCode": 403,
  "message": "Admin access required",
  "error": "Forbidden"
}

Security Considerations

Admin Token Protection

Admin tokens provide full system access:

Never share admin credentials
Regularly rotate API tokens for admin users
Use short-lived JWT tokens where possible
Monitor admin activity via logs

User Management

Best practices:

Limit number of admin users
Review pending users regularly when using review mode
Audit user deletions (permanent action)
Use strong passwords for admin-created accounts

OIDC Configuration

Store client secrets securely
Use HTTPS for all OIDC endpoints
Validate issuer URLs before saving
Test OIDC configuration before disabling internal auth
Keep backup admin account with password access

Overview

Endpoints

Get System Stats

List Users

List Pending Users

Create User

Error Responses

Update User

Error Responses

Delete User

Reset User Password

Approve User

Reject User

Registration Settings

Get Registration Mode

Update Registration Mode

OIDC Settings

Get OIDC Configuration

Update OIDC Configuration

Admin Guard

Security Considerations

Admin Token Protection

User Management

OIDC Configuration

Build docs developers (and LLMs) love

Overview

Endpoints

​Get System Stats

​List Users

​List Pending Users

​Create User

​Error Responses

​Update User

​Error Responses

​Delete User

​Reset User Password

​Approve User

​Reject User

​Registration Settings

​Get Registration Mode

​Update Registration Mode

​OIDC Settings

​Get OIDC Configuration

​Update OIDC Configuration

​Admin Guard

​Security Considerations

​Admin Token Protection

​User Management

​OIDC Configuration

Build docs developers (and LLMs) love

Get System Stats

List Users

List Pending Users

Create User

Error Responses

Update User

Error Responses

Delete User

Reset User Password

Approve User

Reject User

Registration Settings

Get Registration Mode

Update Registration Mode

OIDC Settings

Get OIDC Configuration

Update OIDC Configuration

Admin Guard

Security Considerations

Admin Token Protection

User Management

OIDC Configuration