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

# Users

The end users of your project: create and look up user records and the auth accounts linked to them.

## List authenticated users

`GET /v2/users`

Retrieves an authenticated users.

Users have linked accounts and are authenticated with a provider.

### Query parameters

- `limit` `integer <int32>`: Specifies the maximum number of records to return.
- `skip` `integer <int32>`: Specifies the offset for the first records to return.
- `order` `string`: Specifies the order in which to sort the results.
- `name` `string`: Filter by user name.
- `externalUserId` `string`: Filter by external user ID (accountId from linked accounts).
- `email` `string`: Filter by user email.
- `phoneNumber` `string`: Filter by user phone number.
- `authProviderId` `string`: Filter by provider ID (e.g., "google", "apple", "siwe", "credential").
- `walletClientType` `string`: Filter by wallet client type (for SIWE accounts).

### Responses

#### `200`: Successful response.

Body (`application/json`):

- `object` `string` _(required)_
- `url` `string` _(required)_
- `data` `object[]` _(required)_
  - `id` `string` _(required)_
  - `createdAt` `number <double>` _(required)_
  - `name` `string` _(required)_
  - `email` `string | null` _(required)_
  - `emailVerified` `boolean` _(required)_
  - `phoneNumber` `string | null` _(required)_
  - `phoneNumberVerified` `boolean` _(required)_
  - `isAnonymous` `boolean`
  - `linkedAccounts` `object[]` _(required)_
    - `provider` `string` _(required)_
    - `createdAt` `number <double>` _(required)_
    - `updatedAt` `number <double>` _(required)_
    - `accountId` `string`
    - `chainType` `string`
    - `connectorType` `string`
    - `walletClientType` `string`
- `start` `integer <int32>` _(required)_
- `end` `integer <int32>` _(required)_
- `total` `integer <int32>` _(required)_

#### `401`: Error response.

### Example request

```bash
curl 'https://api.openfort.io/v2/users?limit=10&skip=0&order=desc&name=John&externalUserId=123454456687897&email=user@example.com&phoneNumber=+1234567890&authProviderId=google&walletClientType=metamask'
```

```ts
fetch('https://api.openfort.io/v2/users?limit=10&skip=0&order=desc&name=John&externalUserId=123454456687897&email=user@example.com&phoneNumber=+1234567890&authProviderId=google&walletClientType=metamask')
```

## Get authenticated user by id

`GET /v2/users/{id}`

Retrieves an authenticated user.

Users have linked accounts and are authenticated with a provider.

### Path parameters

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

### Responses

#### `200`: Successful response.

Body (`application/json`):

- `id` `string` _(required)_
- `createdAt` `number <double>` _(required)_
- `name` `string` _(required)_
- `email` `string | null` _(required)_
- `emailVerified` `boolean` _(required)_
- `phoneNumber` `string | null` _(required)_
- `phoneNumberVerified` `boolean` _(required)_
- `isAnonymous` `boolean`
- `linkedAccounts` `object[]` _(required)_
  - `provider` `string` _(required)_
  - `createdAt` `number <double>` _(required)_
  - `updatedAt` `number <double>` _(required)_
  - `accountId` `string`
  - `chainType` `string`
  - `connectorType` `string`
  - `walletClientType` `string`

#### `401`: Error response.

### Example request

```bash
curl https://api.openfort.io/v2/users/pla_e1b24353-1741-4a3d-9e91-2b0fd2942f60
```

```ts
fetch('https://api.openfort.io/v2/users/pla_e1b24353-1741-4a3d-9e91-2b0fd2942f60')
```

## Delete user by id

`DELETE /v2/users/{id}`

It will delete all linked accounts the user is authenticated with.
If the user has a linked embedded signer, it will be deleted as well.

### Path parameters

- `id` `string` _(required)_: Specifies the unique user ID (starts with pla_).

### Responses

#### `200`: Successful response.

Body (`application/json`):

- `id` `string` _(required)_
- `object` `string` _(required)_
- `deleted` `boolean` _(required)_

#### `401`: Error response.

#### `409`: Error response.

### Example request

```bash
curl https://api.openfort.io/v2/users/pla_48eeba57-2cd5-4159-a2cb-057a23a35e65 \
  --request DELETE
```

```ts
fetch('https://api.openfort.io/v2/users/pla_48eeba57-2cd5-4159-a2cb-057a23a35e65', {
  method: 'DELETE'
})
```

## Get wallet for user

`GET /v2/users/{id}/wallet`

Retrieves the wallet associated with an authenticated user.

### Path parameters

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

### Responses

#### `200`: Successful response.

Body (`application/json`):

- `id` `string` _(required)_
- `object` `string` _(required)_
- `createdAt` `integer <int32>` _(required)_

#### `401`: Error response.

#### `404`: User not found.

### Example request

```bash
curl https://api.openfort.io/v2/users/pla_e1b24353-1741-4a3d-9e91-2b0fd2942f60/wallet
```

```ts
fetch('https://api.openfort.io/v2/users/pla_e1b24353-1741-4a3d-9e91-2b0fd2942f60/wallet')
```

## Pre-generate a user with embedded accounts

`POST /v2/users/pregenerate`

Pre-generate a user with one or more embedded accounts before they authenticate.
Creates a user record and an embedded account per entry in `accounts`, each with its
own SSS key shares. When the user later authenticates (via email, OAuth, third-party
auth, etc.) with the same identifier, they will be linked to these pre-generated accounts.

Use the `accounts` array to pregenerate accounts on different chain types
(e.g. one EVM account and one SVM account) in a single call.

You can pregenerate using either:
- `email`: User will be linked when they authenticate with the same email
- `thirdPartyUserId` + `thirdPartyProvider`: User will be linked when they authenticate via the same third-party provider

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

- `email` `string`: The email address of the user to pregenerate. Required if thirdPartyUserId is not provided.
- `thirdPartyUserId` `string`: The third-party user ID from an external auth provider (Firebase, Supabase, etc.). Required if email is not provided.
- `thirdPartyProvider` `string`: The third-party auth provider. Required when thirdPartyUserId is provided.
- `accounts` `object[]` _(required)_: One or more embedded accounts to pregenerate for the user. Each entry produces its own key material and recovery share. Use this to pregenerate accounts on different chain types (e.g. EVM and SVM) in a single call.
  - `accountType` `string`: The type of account to pregenerate. "Externally Owned Account", "Smart Account" or "Delegated Account". Defaults to "Externally Owned Account".
  - `chainType` `string`: The chain type. "EVM" or "SVM". Defaults to "EVM".
  - `chainId` `integer <int32>`: The chain ID. Required for Smart Account and Delegated Account types. Must be a [supported chain](https://www.openfort.io/docs/configuration/chains).
  - `implementationType` `string`: The implementation type for Smart Account or Delegated Account (e.g. Calibur, UpgradeableV6). Required for Smart Account and Delegated Account types.

### Responses

#### `200`: User and accounts pre-generated successfully.

Body (`application/json`):

- `user` `string` _(required)_: User uuid (starts with `usr_`).
- `accounts` `object[]` _(required)_: The embedded accounts that were pregenerated for this user, in the same order as the `accounts` array in the request.
  - `id` `string` _(required)_
  - `wallet` `string` _(required)_
  - `accountType` `string` _(required)_
  - `address` `string` _(required)_
  - `ownerAddress` `string`
  - `chainType` `string` _(required)_
  - `chainId` `number <double>`
  - `createdAt` `number <double>` _(required)_
  - `updatedAt` `number <double>` _(required)_
  - `smartAccount` `object`
    - `implementationType` `string` _(required)_
    - `factoryAddress` `string`
    - `implementationAddress` `string` _(required)_
    - `salt` `string`
    - `deployedTx` `string`
    - `deployedAt` `number <double>`
    - `active` `boolean` _(required)_
    - `ownerAddress` `string`
    - `chainId` `number <double>`
  - `recoveryMethod` `string`
  - `recoveryMethodDetails` `object`
    - `passkeyId` `string`
    - `passkeyEnv` `object`
      - `name` `string`
      - `os` `string`
      - `osVersion` `string`
      - `device` `string`
  - `custody` `string` _(required)_: Indicates key custody: "Developer" for TEE managed keys, "User" for user-managed keys.
  - `recoveryShare` `string` _(required)_: The recovery share for this embedded account's signer. This should be stored securely and provided to the user for account recovery.
  - `signer` `string` _(required)_: The signer UUID (starts with `sig_`) backing this embedded account. Use this value as the `reference` when storing the recovery share with Shield, so subsequent reads of the account can resolve the recovery method via the signer-reference lookup.

#### `400`: Bad request - invalid parameters.

#### `401`: Unauthorized - invalid API key.

#### `409`: Conflict - user with this identifier already exists.

### Example request

```bash
curl https://api.openfort.io/v2/users/pregenerate \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "user@example.com",
  "thirdPartyUserId": "firebase_uid_abc123",
  "thirdPartyProvider": "firebase",
  "accounts": [
    {
      "accountType": "Externally Owned Account",
      "chainType": "EVM",
      "chainId": 137,
      "implementationType": "Calibur"
    }
  ]
}'
```

```ts
fetch('https://api.openfort.io/v2/users/pregenerate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    thirdPartyUserId: 'firebase_uid_abc123',
    thirdPartyProvider: 'firebase',
    accounts: [
      {
        accountType: 'Externally Owned Account',
        chainType: 'EVM',
        chainId: 137,
        implementationType: 'Calibur'
      }
    ]
  })
})
```

## Get user information

`GET /iam/v2/me`

### Responses

#### `200`: Successful response.

Body (`application/json`):

- `id` `string` _(required)_
- `createdAt` `number <double>` _(required)_
- `name` `string` _(required)_
- `email` `string | null` _(required)_
- `emailVerified` `boolean` _(required)_
- `phoneNumber` `string | null` _(required)_
- `phoneNumberVerified` `boolean` _(required)_
- `isAnonymous` `boolean`
- `linkedAccounts` `object[]` _(required)_
  - `provider` `string` _(required)_
  - `createdAt` `number <double>` _(required)_
  - `updatedAt` `number <double>` _(required)_
  - `accountId` `string`
  - `chainType` `string`
  - `connectorType` `string`
  - `walletClientType` `string`

#### `401`: Error response.

### Example request

```bash
curl https://api.openfort.io/iam/v2/me
```

```ts
fetch('https://api.openfort.io/iam/v2/me')
```

## Verify oauth token of a third party auth provider

`POST /iam/v2/user/third_party`

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

- `provider` `string` _(required)_: OAuth provider
- `token` `string` _(required)_: Token to be verified
- `tokenType` `string`: Enum of the supporting OAuth providers.

### Responses

#### `200`: Ok

Body (`application/json`):

- `id` `string` _(required)_
- `createdAt` `number <double>` _(required)_
- `name` `string` _(required)_
- `email` `string | null` _(required)_
- `emailVerified` `boolean` _(required)_
- `phoneNumber` `string | null` _(required)_
- `phoneNumberVerified` `boolean` _(required)_
- `isAnonymous` `boolean`
- `linkedAccounts` `object[]` _(required)_
  - `provider` `string` _(required)_
  - `createdAt` `number <double>` _(required)_
  - `updatedAt` `number <double>` _(required)_
  - `accountId` `string`
  - `chainType` `string`
  - `connectorType` `string`
  - `walletClientType` `string`

#### `401`

### Example request

```bash
curl https://api.openfort.io/iam/v2/user/third_party \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "firebase",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  "tokenType": "idToken"
}'
```

```ts
fetch('https://api.openfort.io/iam/v2/user/third_party', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    provider: 'firebase',
    token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9',
    tokenType: 'idToken'
  })
})
```