> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.prividium.com/api/mcp` to find what you need.
>
> **Have feedback?** Use `submit_feedback` on the same MCP server.

# users

User management endpoints

## GET /users/

`GET /users/`

List users, oldest first (createdAt, then id). With MULTI_ORG_ENABLED the list is zone-level by default: scope=all covers the whole zone, organizationId scopes to one organization, and sort=organization lists zone users before members.

### Query parameters

- `limit` `integer`
- `offset` `integer`
- `roleId` `string`
- `displayName` `string`
- `scope` `string`
- `organizationId` `string`
- `sort` `string`

### Responses

#### `200`: Default Response

Body (`application/json`):

- `items` `object[]` _(required)_
  - `id` `string` _(required)_
  - `displayName` `string` _(required)_
  - `source` `string` _(required)_
  - `suspendedAt` `string <date-time>` _(required)_
  - `createdAt` `string <date-time>` _(required)_
  - `updatedAt` `string <date-time>` _(required)_
  - `organization` `object` _(required)_
    - `id` `string` _(required)_
    - `name` `string` _(required)_
  - `roles` `object[]` _(required)_
    - `id` `string` _(required)_
    - `roleName` `string` _(required)_
    - `systemPermissions` `string[]`
    - `isSystemRole` `boolean`
    - `organizationId` `string | null`
    - `createdAt` `string <date-time>`
    - `updatedAt` `string <date-time>`
  - `wallets` `object[]` _(required)_
    - `id` `integer` _(required)_
    - `walletAddress` `string` _(required)_
    - `userId` `string` _(required)_
    - `createdAt` `string <date-time>` _(required)_
    - `updatedAt` `string <date-time>` _(required)_
- `pagination` `object` _(required)_
  - `currentPage` `number` _(required)_
  - `totalPages` `number` _(required)_
  - `totalItems` `number` _(required)_
  - `limit` `number` _(required)_
  - `offset` `number` _(required)_

#### `400`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

#### `401`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

#### `403`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

### Example request

```bash
curl '/api/users/?limit=10&offset=0&roleId=string&displayName=string&scope=zone&organizationId=string&sort=created'
```

```ts
fetch('/api/users/?limit=10&offset=0&roleId=string&displayName=string&scope=zone&organizationId=string&sort=created')
```

## POST /users/

`POST /users/`

Create a new user

### Request body (required) (`application/json`)

- `oidcSub` `string | null`
- `oidcIssuer` `string | null`
- `displayName` `string` _(required)_
- `organizationId` `string | null`
- `roles` `string[]`
- `wallets` `string[]`

### Responses

#### `201`: Default Response

Body (`application/json`):

- `id` `string` _(required)_
- `displayName` `string` _(required)_
- `source` `string` _(required)_
- `suspendedAt` `string <date-time>` _(required)_
- `createdAt` `string <date-time>` _(required)_
- `updatedAt` `string <date-time>` _(required)_
- `organization` `object` _(required)_
  - `id` `string` _(required)_
  - `name` `string` _(required)_
- `roles` `object[]` _(required)_
  - `id` `string` _(required)_
  - `roleName` `string` _(required)_
  - `systemPermissions` `string[]`
  - `isSystemRole` `boolean`
  - `organizationId` `string | null`
  - `createdAt` `string <date-time>`
  - `updatedAt` `string <date-time>`
- `wallets` `object[]` _(required)_
  - `id` `integer` _(required)_
  - `walletAddress` `string` _(required)_
  - `userId` `string` _(required)_
  - `createdAt` `string <date-time>` _(required)_
  - `updatedAt` `string <date-time>` _(required)_

#### `400`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

#### `409`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

### Example request

```bash
curl /api/users/ \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "oidcSub": "string",
  "oidcIssuer": "string",
  "displayName": "string",
  "organizationId": "string",
  "roles": [
    "string"
  ],
  "wallets": [
    "string"
  ]
}'
```

```ts
fetch('/api/users/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    oidcSub: 'string',
    oidcIssuer: 'string',
    displayName: 'string',
    organizationId: 'string',
    roles: ['string'],
    wallets: ['string']
  })
})
```

## GET /users/watchdog-grant

`GET /users/watchdog-grant`

The watchdog's code-defined grant on /rpc, /admit and /judge

### Responses

#### `200`: Default Response

Body (`application/json`):

- `rpcMethods` `string[]` _(required)_
- `calls` `object[]` _(required)_
  - `contract` `string` _(required)_
  - `function` `string` _(required)_
  - `ownRecipientOnly` `boolean` _(required)_
- `events` `object[]` _(required)_
  - `contract` `string` _(required)_
  - `event` `string` _(required)_
  - `ownSenderOnly` `boolean` _(required)_

#### `401`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

#### `403`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

### Example request

```bash
curl /api/users/watchdog-grant
```

```ts
fetch('/api/users/watchdog-grant')
```

## GET /users/{id}

`GET /users/{id}`

Get a user by ID

### Path parameters

- `id` `string` _(required)_

### Responses

#### `200`: Default Response

Body (`application/json`):

- `id` `string` _(required)_
- `displayName` `string` _(required)_
- `source` `string` _(required)_
- `suspendedAt` `string <date-time>` _(required)_
- `createdAt` `string <date-time>` _(required)_
- `updatedAt` `string <date-time>` _(required)_
- `organization` `object` _(required)_
  - `id` `string` _(required)_
  - `name` `string` _(required)_
- `roles` `object[]` _(required)_
  - `id` `string` _(required)_
  - `roleName` `string` _(required)_
  - `systemPermissions` `string[]`
  - `isSystemRole` `boolean`
  - `organizationId` `string | null`
  - `createdAt` `string <date-time>`
  - `updatedAt` `string <date-time>`
- `wallets` `object[]` _(required)_
  - `id` `integer` _(required)_
  - `walletAddress` `string` _(required)_
  - `userId` `string` _(required)_
  - `createdAt` `string <date-time>` _(required)_
  - `updatedAt` `string <date-time>` _(required)_

#### `400`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

#### `404`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

### Example request

```bash
curl /api/users/string
```

```ts
fetch('/api/users/string')
```

## PUT /users/{id}

`PUT /users/{id}`

Replace a user (full update)

### Path parameters

- `id` `string` _(required)_

### Request body (required) (`application/json`)

- `displayName` `string` _(required)_
- `roles` `string[]` _(required)_
- `wallets` `string[]` _(required)_

### Responses

#### `200`: Default Response

Body (`application/json`):

- `id` `string` _(required)_
- `displayName` `string` _(required)_
- `source` `string` _(required)_
- `suspendedAt` `string <date-time>` _(required)_
- `createdAt` `string <date-time>` _(required)_
- `updatedAt` `string <date-time>` _(required)_
- `organization` `object` _(required)_
  - `id` `string` _(required)_
  - `name` `string` _(required)_
- `roles` `object[]` _(required)_
  - `id` `string` _(required)_
  - `roleName` `string` _(required)_
  - `systemPermissions` `string[]`
  - `isSystemRole` `boolean`
  - `organizationId` `string | null`
  - `createdAt` `string <date-time>`
  - `updatedAt` `string <date-time>`
- `wallets` `object[]` _(required)_
  - `id` `integer` _(required)_
  - `walletAddress` `string` _(required)_
  - `userId` `string` _(required)_
  - `createdAt` `string <date-time>` _(required)_
  - `updatedAt` `string <date-time>` _(required)_

#### `400`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

#### `404`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

#### `409`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

### Example request

```bash
curl /api/users/string \
  --request PUT \
  --header 'Content-Type: application/json' \
  --data '{
  "displayName": "string",
  "roles": [
    "string"
  ],
  "wallets": [
    "string"
  ]
}'
```

```ts
fetch('/api/users/string', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    displayName: 'string',
    roles: ['string'],
    wallets: ['string']
  })
})
```

## DELETE /users/{id}

`DELETE /users/{id}`

Delete a user

### Path parameters

- `id` `string` _(required)_

### Responses

#### `204`: Default Response

#### `400`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

#### `404`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

### Example request

```bash
curl /api/users/string \
  --request DELETE
```

```ts
fetch('/api/users/string', {
  method: 'DELETE'
})
```

## POST /users/{id}/suspend

`POST /users/{id}/suspend`

Suspend the watchdog user: revokes its sessions and refuses its logins and transactions until resumed

### Path parameters

- `id` `string` _(required)_

### Responses

#### `200`: Default Response

Body (`application/json`):

- `id` `string` _(required)_
- `displayName` `string` _(required)_
- `source` `string` _(required)_
- `suspendedAt` `string <date-time>` _(required)_
- `createdAt` `string <date-time>` _(required)_
- `updatedAt` `string <date-time>` _(required)_
- `organization` `object` _(required)_
  - `id` `string` _(required)_
  - `name` `string` _(required)_
- `roles` `object[]` _(required)_
  - `id` `string` _(required)_
  - `roleName` `string` _(required)_
  - `systemPermissions` `string[]`
  - `isSystemRole` `boolean`
  - `organizationId` `string | null`
  - `createdAt` `string <date-time>`
  - `updatedAt` `string <date-time>`
- `wallets` `object[]` _(required)_
  - `id` `integer` _(required)_
  - `walletAddress` `string` _(required)_
  - `userId` `string` _(required)_
  - `createdAt` `string <date-time>` _(required)_
  - `updatedAt` `string <date-time>` _(required)_

#### `400`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

#### `404`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

### Example request

```bash
curl /api/users/string/suspend \
  --request POST
```

```ts
fetch('/api/users/string/suspend', {
  method: 'POST'
})
```

## POST /users/{id}/resume

`POST /users/{id}/resume`

Resume the suspended watchdog user

### Path parameters

- `id` `string` _(required)_

### Responses

#### `200`: Default Response

Body (`application/json`):

- `id` `string` _(required)_
- `displayName` `string` _(required)_
- `source` `string` _(required)_
- `suspendedAt` `string <date-time>` _(required)_
- `createdAt` `string <date-time>` _(required)_
- `updatedAt` `string <date-time>` _(required)_
- `organization` `object` _(required)_
  - `id` `string` _(required)_
  - `name` `string` _(required)_
- `roles` `object[]` _(required)_
  - `id` `string` _(required)_
  - `roleName` `string` _(required)_
  - `systemPermissions` `string[]`
  - `isSystemRole` `boolean`
  - `organizationId` `string | null`
  - `createdAt` `string <date-time>`
  - `updatedAt` `string <date-time>`
- `wallets` `object[]` _(required)_
  - `id` `integer` _(required)_
  - `walletAddress` `string` _(required)_
  - `userId` `string` _(required)_
  - `createdAt` `string <date-time>` _(required)_
  - `updatedAt` `string <date-time>` _(required)_

#### `400`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

#### `404`: Default Response

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `issues` `unknown[]`

### Example request

```bash
curl /api/users/string/resume \
  --request POST
```

```ts
fetch('/api/users/string/resume', {
  method: 'POST'
})
```