> **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 an embedded account

`POST /v2/users/pregenerate`

Pre-generate a user with an embedded account before they authenticate.
Creates a user record and an embedded account using the provided SSS key shares.
When the user later authenticates (via email, OAuth, third-party auth, etc.)
with the same identifier, they will be linked to this pre-generated account.

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.
- `accountType` `string`: The type of account to pregenerate. "Externally Owned Account", "Smart Account" or "Delegated Account". Defaults to "Smart 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 account pre-generated successfully.

Body (`application/json`):

- `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 the user's embedded signer. This should be stored securely and provided to the user for account recovery.
- `user` `string` _(required)_: User uuid

#### `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",
  "accountType": "Smart 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',
    accountType: 'Smart 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'
  })
})
```