> **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>`: Maximum number of records to return per page. Defaults to 10.
- `skip` `integer <int32>`: Number of records to skip before the first one returned. Defaults to 0. Combine with `limit` to page through results.
- `order` `string`: Sort direction by creation date: `asc` (oldest first) or `desc`. Defaults to `desc` (newest first).
- `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`: A page of users.

Body (`application/json`):

- `object` `string` _(required)_: The type of object. Always `list`.
- `url` `string` _(required)_: Path of the endpoint that produced this page.
- `data` `object[]` _(required)_: The items on this page.
  - `id` `string` _(required)_: The user ID (starts with `usr_`).
  - `createdAt` `integer <int32>` _(required)_: When the user was created, as Unix epoch seconds.
  - `name` `string` _(required)_: The user's display name.
  - `email` `string | null` _(required)_: The user's email address, or `null` when they have none (anonymous users).
  - `emailVerified` `boolean` _(required)_: Whether the email address has been verified.
  - `phoneNumber` `string | null` _(required)_: The user's phone number, or `null` when none is linked.
  - `phoneNumberVerified` `boolean` _(required)_: Whether the phone number has been verified.
  - `isAnonymous` `boolean`: Whether this is an anonymous (guest) user.
  - `linkedAccounts` `object[]` _(required)_: The authentication methods linked to this user.
    - `provider` `string` _(required)_: The authentication provider this account was linked through.
    - `createdAt` `integer <int32>` _(required)_: When the account was linked, as Unix epoch seconds.
    - `updatedAt` `integer <int32>` _(required)_: When the linked account was last updated, as Unix epoch seconds.
    - `accountId` `string`: The user's identifier at the provider: the wallet address for `siwe`, the provider's user ID for social providers. Absent for `credential` (email and password).
    - `chainType` `string`: Chain family of the linked wallet (`EVM` or `SVM`). Only present for wallet-based providers.
    - `connectorType` `string`: How the wallet connected, for example `injected` or `wallet_connect`. Only present for wallet-based providers.
    - `walletClientType` `string`: The wallet application used, for example `metamask`. Only present for wallet-based providers.
- `start` `integer <int32>` _(required)_: Zero-based offset of the first item on this page (the `skip` you passed, default 0).
- `end` `integer <int32>` _(required)_: Offset just past the last item on this page (`start` plus the page size).
- `total` `integer <int32>` _(required)_: Total number of items matching the query across all pages.

#### `401`: Missing or invalid credentials.

### 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`: The user.

Body (`application/json`):

- `id` `string` _(required)_: The user ID (starts with `usr_`).
- `createdAt` `integer <int32>` _(required)_: When the user was created, as Unix epoch seconds.
- `name` `string` _(required)_: The user's display name.
- `email` `string | null` _(required)_: The user's email address, or `null` when they have none (anonymous users).
- `emailVerified` `boolean` _(required)_: Whether the email address has been verified.
- `phoneNumber` `string | null` _(required)_: The user's phone number, or `null` when none is linked.
- `phoneNumberVerified` `boolean` _(required)_: Whether the phone number has been verified.
- `isAnonymous` `boolean`: Whether this is an anonymous (guest) user.
- `linkedAccounts` `object[]` _(required)_: The authentication methods linked to this user.
  - `provider` `string` _(required)_: The authentication provider this account was linked through.
  - `createdAt` `integer <int32>` _(required)_: When the account was linked, as Unix epoch seconds.
  - `updatedAt` `integer <int32>` _(required)_: When the linked account was last updated, as Unix epoch seconds.
  - `accountId` `string`: The user's identifier at the provider: the wallet address for `siwe`, the provider's user ID for social providers. Absent for `credential` (email and password).
  - `chainType` `string`: Chain family of the linked wallet (`EVM` or `SVM`). Only present for wallet-based providers.
  - `connectorType` `string`: How the wallet connected, for example `injected` or `wallet_connect`. Only present for wallet-based providers.
  - `walletClientType` `string`: The wallet application used, for example `metamask`. Only present for wallet-based providers.

#### `401`: Missing or invalid credentials.

### 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`: The deleted user.

Body (`application/json`):

- `id` `string` _(required)_: Identifier of the deleted object.
- `object` `string` _(required)_: The type of the deleted object.
- `deleted` `boolean` _(required)_: Always `true`: the object was deleted.

#### `401`: Missing or invalid credentials.

#### `409`: The request conflicts with the current state of the resource.

### 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`: The user's wallet.

Body (`application/json`):

- `id` `string` _(required)_: Unique identifier of the object. The prefix tells its type, for example `acc_` for accounts.
- `object` `string` _(required)_: The type of object.
- `createdAt` `integer <int32>` _(required)_: When the object was created, as Unix epoch seconds.

#### `401`: Missing or invalid credentials.

#### `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)_: The account ID (starts with `acc_`).
  - `wallet` `string` _(required)_: ID of the wallet this account belongs to (starts with `pla_`). A user's wallet groups all of their accounts.
  - `accountType` `string` _(required)_: The kind of account: `Externally Owned Account`, `Smart Account` or `Delegated Account`.
  - `address` `string` _(required)_: The onchain address of the account.
  - `ownerAddress` `string`: Address of the key that controls a smart account. Absent for externally owned and delegated accounts, whose address is the key itself.
  - `chainType` `string` _(required)_: The chain family: `EVM` or `SVM`.
  - `chainId` `integer <int32>`: Chain ID the account was created on, when known.
  - `createdAt` `integer <int32>` _(required)_: When the account was created, as Unix epoch seconds.
  - `updatedAt` `integer <int32>` _(required)_: When the account was last updated, as Unix epoch seconds.
  - `smartAccount` `object`: Smart account details. Only present for smart and delegated accounts.
    - `implementationType` `string` _(required)_: The smart account implementation, for example `UpgradeableV6`, `UpgradeableV5`, `Calibur`, `CaliburV9`, `ManagedV5` or `Simple`.
    - `factoryAddress` `string`: Address of the factory contract that deploys the account. Absent for delegated accounts, whose address already exists.
    - `implementationAddress` `string` _(required)_: Address of the implementation contract the account delegates to.
    - `salt` `string`: Salt used to derive the counterfactual account address. Absent for delegated accounts, which are not counterfactually deployed.
    - `deployedTx` `string`: Hash of the transaction that deployed the account onchain. Absent until the account is deployed.
    - `deployedAt` `integer <int32>`: When the account was deployed onchain, as Unix epoch seconds. Absent until the account is deployed.
    - `active` `boolean` _(required)_: Whether this smart account configuration is the one currently in use for the account.
    - `ownerAddress` `string`: Address of the key that controls the smart account, when available.
    - `chainId` `integer <int32>`: Chain ID the smart account lives on, when available.
  - `recoveryMethod` `string`: How the user recovers their share of the signer, for example `password`, `passkey` or `automatic`. Only present for user-custody accounts.
  - `recoveryMethodDetails` `object`: Details of the recovery method. Only present when it is a passkey.
    - `passkeyId` `string`: Identifier of the passkey that protects the recovery share.
    - `passkeyEnv` `object`: Environment the passkey was registered in, as reported by the client.
      - `name` `string`: Name of the client (browser or app) that registered the passkey.
      - `os` `string`: Operating system of the device that registered the passkey.
      - `osVersion` `string`: Version of that operating system.
      - `device` `string`: Device that registered the passkey.
  - `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`: The authenticated user.

Body (`application/json`):

- `id` `string` _(required)_: The user ID (starts with `usr_`).
- `createdAt` `integer <int32>` _(required)_: When the user was created, as Unix epoch seconds.
- `name` `string` _(required)_: The user's display name.
- `email` `string | null` _(required)_: The user's email address, or `null` when they have none (anonymous users).
- `emailVerified` `boolean` _(required)_: Whether the email address has been verified.
- `phoneNumber` `string | null` _(required)_: The user's phone number, or `null` when none is linked.
- `phoneNumberVerified` `boolean` _(required)_: Whether the phone number has been verified.
- `isAnonymous` `boolean`: Whether this is an anonymous (guest) user.
- `linkedAccounts` `object[]` _(required)_: The authentication methods linked to this user.
  - `provider` `string` _(required)_: The authentication provider this account was linked through.
  - `createdAt` `integer <int32>` _(required)_: When the account was linked, as Unix epoch seconds.
  - `updatedAt` `integer <int32>` _(required)_: When the linked account was last updated, as Unix epoch seconds.
  - `accountId` `string`: The user's identifier at the provider: the wallet address for `siwe`, the provider's user ID for social providers. Absent for `credential` (email and password).
  - `chainType` `string`: Chain family of the linked wallet (`EVM` or `SVM`). Only present for wallet-based providers.
  - `connectorType` `string`: How the wallet connected, for example `injected` or `wallet_connect`. Only present for wallet-based providers.
  - `walletClientType` `string`: The wallet application used, for example `metamask`. Only present for wallet-based providers.

#### `401`: Missing or invalid credentials.

### 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`: Kind of token being verified: `idToken` or `customToken` (default). Only relevant for providers that issue both, such as Firebase.

### Responses

#### `200`: The verified user.

Body (`application/json`):

- `id` `string` _(required)_: The user ID (starts with `usr_`).
- `createdAt` `integer <int32>` _(required)_: When the user was created, as Unix epoch seconds.
- `name` `string` _(required)_: The user's display name.
- `email` `string | null` _(required)_: The user's email address, or `null` when they have none (anonymous users).
- `emailVerified` `boolean` _(required)_: Whether the email address has been verified.
- `phoneNumber` `string | null` _(required)_: The user's phone number, or `null` when none is linked.
- `phoneNumberVerified` `boolean` _(required)_: Whether the phone number has been verified.
- `isAnonymous` `boolean`: Whether this is an anonymous (guest) user.
- `linkedAccounts` `object[]` _(required)_: The authentication methods linked to this user.
  - `provider` `string` _(required)_: The authentication provider this account was linked through.
  - `createdAt` `integer <int32>` _(required)_: When the account was linked, as Unix epoch seconds.
  - `updatedAt` `integer <int32>` _(required)_: When the linked account was last updated, as Unix epoch seconds.
  - `accountId` `string`: The user's identifier at the provider: the wallet address for `siwe`, the provider's user ID for social providers. Absent for `credential` (email and password).
  - `chainType` `string`: Chain family of the linked wallet (`EVM` or `SVM`). Only present for wallet-based providers.
  - `connectorType` `string`: How the wallet connected, for example `injected` or `wallet_connect`. Only present for wallet-based providers.
  - `walletClientType` `string`: The wallet application used, for example `metamask`. Only present for wallet-based providers.

#### `400`: The provider token could not be verified.

#### `401`: The publishable key is missing or invalid.

#### `404`: No auth provider of this type is configured in the environment.

### 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'
  })
})
```