Dynamic Embedded Wallets API
Programmatically create MPC-TSS embedded wallets for users, generating self-custodial keys split across parties without seed phrases.
OpenAPI Specification
openapi: 3.0.3
info:
title: Dynamic API
description: >-
Representative OpenAPI description of the Dynamic environment-scoped REST API
for web3 authentication and embedded wallets. Admin endpoints authenticate
with an environment-scoped bearer API token (dyn_ prefixed); SDK endpoints
authenticate with a user JWT obtained via the client SDK. This document is a
faithful, non-exhaustive representation of publicly documented surfaces at
https://docs.dynamic.xyz/api-reference. Consult the live API reference for the
complete schema catalog.
termsOfService: https://www.dynamic.xyz/terms
contact:
name: Dynamic Support
url: https://www.dynamic.xyz/contact
version: 'v0'
servers:
- url: https://app.dynamicauth.com/api/v0
description: Production
- url: https://app.dynamic.xyz/api/v0
description: Production (alternate host)
security:
- bearerAuth: []
tags:
- name: Users
description: List and manage end users authenticated into an environment.
- name: Wallets
description: View and manage wallets linked to users.
- name: Embedded Wallets
description: Provision MPC-TSS embedded wallets for users.
- name: Environments
description: Retrieve and update environment (project) configuration.
- name: API Tokens
description: Create and revoke environment-scoped API tokens.
- name: Webhooks
description: Manage webhook endpoints for event notifications.
- name: JWKS
description: Fetch the JSON Web Key Set used to verify Dynamic JWTs.
- name: Allowlists
description: Gate authentication with allowlists.
- name: Analytics
description: Retrieve aggregate environment analytics.
- name: Exports
description: Download data exports.
paths:
/environments/{environmentId}:
get:
operationId: getEnvironment
tags:
- Environments
summary: Get an environment by ID.
description: Returns the configuration and settings for the specified environment (project).
parameters:
- $ref: '#/components/parameters/EnvironmentId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Environment'
'401':
$ref: '#/components/responses/Unauthorized'
patch:
operationId: updateEnvironment
tags:
- Environments
summary: Update an environment.
description: Updates settings for the specified environment.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentUpdate'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Environment'
'401':
$ref: '#/components/responses/Unauthorized'
/environments/{environmentId}/users:
get:
operationId: getUsers
tags:
- Users
summary: Get users for an environment.
description: Returns a paginated list of users authenticated into the specified environment.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
- name: filterValue
in: query
required: false
description: Optional filter (for example an email or alias) to search users by.
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
'401':
$ref: '#/components/responses/Unauthorized'
/environments/{environmentId}/users/{userId}:
get:
operationId: getUserById
tags:
- Users
summary: Get a user by ID.
description: Returns the specified user, including linked verified credentials.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
- $ref: '#/components/parameters/UserId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateUser
tags:
- Users
summary: Update a user.
description: Updates metadata and fields for the specified user.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
- $ref: '#/components/parameters/UserId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserUpdate'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteUser
tags:
- Users
summary: Delete a user.
description: Permanently deletes the specified user from the environment.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
- $ref: '#/components/parameters/UserId'
responses:
'204':
description: User deleted.
'401':
$ref: '#/components/responses/Unauthorized'
/environments/{environmentId}/users/{userId}/wallets:
get:
operationId: getWalletsByUserId
tags:
- Wallets
summary: Get wallets by user.
description: Returns the wallets linked to the specified user.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
- $ref: '#/components/parameters/UserId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WalletList'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createEmbeddedWallet
tags:
- Embedded Wallets
summary: Create an embedded wallet for a user.
description: >-
Creates a new MPC-TSS embedded wallet for the specified user. Fails if the
user already has an embedded wallet of the requested chain linked.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
- $ref: '#/components/parameters/UserId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmbeddedWalletRequest'
responses:
'201':
description: Wallet created.
content:
application/json:
schema:
$ref: '#/components/schemas/Wallet'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/environments/{environmentId}/tokens:
get:
operationId: getApiTokens
tags:
- API Tokens
summary: Get API tokens for an environment.
description: Returns the API tokens issued for the specified environment.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ApiTokenList'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createApiToken
tags:
- API Tokens
summary: Create a new API token.
description: Creates a new API token for the specified environment.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateApiTokenRequest'
responses:
'201':
description: Token created.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiToken'
'401':
$ref: '#/components/responses/Unauthorized'
/environments/{environmentId}/tokens/{tokenId}:
delete:
operationId: deleteApiToken
tags:
- API Tokens
summary: Delete an API token.
description: Revokes and deletes the specified API token.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
- name: tokenId
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Token deleted.
'401':
$ref: '#/components/responses/Unauthorized'
/environments/{environmentId}/webhooks:
get:
operationId: getWebhooks
tags:
- Webhooks
summary: Get webhooks for an environment.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookList'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createWebhook
tags:
- Webhooks
summary: Create a webhook.
description: Registers a new webhook endpoint subscribed to the given event scopes.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookRequest'
responses:
'201':
description: Webhook created.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
'401':
$ref: '#/components/responses/Unauthorized'
/environments/{environmentId}/webhooks/{webhookId}:
get:
operationId: getWebhookById
tags:
- Webhooks
summary: Get a webhook by ID.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
- $ref: '#/components/parameters/WebhookId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
'401':
$ref: '#/components/responses/Unauthorized'
put:
operationId: updateWebhook
tags:
- Webhooks
summary: Update a webhook.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
- $ref: '#/components/parameters/WebhookId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteWebhook
tags:
- Webhooks
summary: Delete a webhook.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
- $ref: '#/components/parameters/WebhookId'
responses:
'204':
description: Webhook deleted.
'401':
$ref: '#/components/responses/Unauthorized'
/environments/{environmentId}/allowlists:
get:
operationId: getAllowlists
tags:
- Allowlists
summary: Get allowlists for an environment.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AllowlistList'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createAllowlist
tags:
- Allowlists
summary: Create an allowlist.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAllowlistRequest'
responses:
'201':
description: Allowlist created.
content:
application/json:
schema:
$ref: '#/components/schemas/Allowlist'
'401':
$ref: '#/components/responses/Unauthorized'
/environments/{environmentId}/allowlists/{allowlistId}/entries:
post:
operationId: createAllowlistEntry
tags:
- Allowlists
summary: Add an entry to an allowlist.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
- name: allowlistId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AllowlistEntry'
responses:
'201':
description: Entry created.
content:
application/json:
schema:
$ref: '#/components/schemas/AllowlistEntry'
'401':
$ref: '#/components/responses/Unauthorized'
/environments/{environmentId}/analytics/wallets:
get:
operationId: getAnalyticsWallets
tags:
- Analytics
summary: Get wallet analytics for an environment.
description: Returns aggregate wallet analytics for the environment over an optional date range.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
- name: startDate
in: query
required: false
schema:
type: string
format: date
- name: endDate
in: query
required: false
schema:
type: string
format: date
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WalletAnalytics'
'401':
$ref: '#/components/responses/Unauthorized'
/environments/{environmentId}/exports/{exportId}:
get:
operationId: downloadExport
tags:
- Exports
summary: Download an export by ID.
description: Returns the file content for a previously requested data export.
parameters:
- $ref: '#/components/parameters/EnvironmentId'
- name: exportId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/octet-stream:
schema:
type: string
format: binary
'401':
$ref: '#/components/responses/Unauthorized'
/sdk/{environmentId}/.well-known/jwks.json:
get:
operationId: getJwks
tags:
- JWKS
summary: Find JWKS for public key (JSON format).
description: >-
Returns the JSON Web Key Set (JWKS) for the environment, used to verify the
signature of Dynamic-issued JWT auth tokens server-side. This endpoint does
not require authentication.
security: []
parameters:
- $ref: '#/components/parameters/EnvironmentId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Jwks'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: dyn_token
description: >-
Environment-scoped API token with a dyn_ prefix for admin endpoints, or a
user JWT from the client SDK for SDK endpoints. Sent as
Authorization: Bearer <token>.
parameters:
EnvironmentId:
name: environmentId
in: path
required: true
description: The ID of the Dynamic environment (project).
schema:
type: string
format: uuid
UserId:
name: userId
in: path
required: true
description: The ID of the user.
schema:
type: string
format: uuid
WebhookId:
name: webhookId
in: path
required: true
description: The ID of the webhook.
schema:
type: string
format: uuid
Limit:
name: limit
in: query
required: false
description: Maximum number of items to return.
schema:
type: integer
default: 100
maximum: 1000
Offset:
name: offset
in: query
required: false
description: Number of items to skip for pagination.
schema:
type: integer
default: 0
responses:
Unauthorized:
description: The bearer token is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: The request was malformed or a precondition failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
required:
- message
required:
- error
Environment:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
live:
type: boolean
description: Whether this is a live (true) or sandbox (false) environment.
projectSettings:
type: object
additionalProperties: true
EnvironmentUpdate:
type: object
properties:
name:
type: string
projectSettings:
type: object
additionalProperties: true
User:
type: object
properties:
id:
type: string
format: uuid
email:
type: string
format: email
nullable: true
alias:
type: string
nullable: true
firstVisit:
type: string
format: date-time
lastVisit:
type: string
format: date-time
verifiedCredentials:
type: array
items:
$ref: '#/components/schemas/VerifiedCredential'
required:
- id
UserUpdate:
type: object
properties:
email:
type: string
format: email
alias:
type: string
metadata:
type: object
additionalProperties: true
UserList:
type: object
properties:
users:
type: array
items:
$ref: '#/components/schemas/User'
count:
type: integer
VerifiedCredential:
type: object
properties:
id:
type: string
format: uuid
format:
type: string
enum:
- blockchain
- email
- oauth
address:
type: string
nullable: true
chain:
type: string
nullable: true
walletName:
type: string
nullable: true
Wallet:
type: object
properties:
id:
type: string
format: uuid
address:
type: string
chain:
type: string
description: The blockchain family, for example EVM, SOL, or BTC.
walletProvider:
type: string
description: How the wallet is provisioned, for example embeddedWallet or browserExtension.
name:
type: string
publicKey:
type: string
nullable: true
WalletList:
type: object
properties:
wallets:
type: array
items:
$ref: '#/components/schemas/Wallet'
CreateEmbeddedWalletRequest:
type: object
properties:
chains:
type: array
description: The chains to provision embedded wallets for.
items:
type: string
enum:
- EVM
- SOL
- BTC
required:
- chains
ApiToken:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
token:
type: string
description: The dyn_ prefixed secret, returned only on creation.
nullable: true
createdAt:
type: string
format: date-time
expiresAt:
type: string
format: date-time
nullable: true
ApiTokenList:
type: object
properties:
tokens:
type: array
items:
$ref: '#/components/schemas/ApiToken'
CreateApiTokenRequest:
type: object
properties:
name:
type: string
expiresAt:
type: string
format: date-time
nullable: true
required:
- name
Webhook:
type: object
properties:
id:
type: string
format: uuid
url:
type: string
format: uri
isEnabled:
type: boolean
scopes:
type: array
items:
type: string
description: Event scope such as user.created, wallet.linked, or user.session.created.
secret:
type: string
description: Signing secret used to verify webhook payloads, returned only on creation.
nullable: true
WebhookList:
type: object
properties:
webhooks:
type: array
items:
$ref: '#/components/schemas/Webhook'
CreateWebhookRequest:
type: object
properties:
url:
type: string
format: uri
isEnabled:
type: boolean
default: true
scopes:
type: array
items:
type: string
required:
- url
- scopes
Allowlist:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
type:
type: string
enum:
- email
- walletAddress
- country
entries:
type: array
items:
$ref: '#/components/schemas/AllowlistEntry'
AllowlistList:
type: object
properties:
allowlists:
type: array
items:
$ref: '#/components/schemas/Allowlist'
CreateAllowlistRequest:
type: object
properties:
name:
type: string
type:
type: string
enum:
- email
- walletAddress
- country
required:
- name
- type
AllowlistEntry:
type: object
properties:
id:
type: string
format: uuid
value:
type: string
description: The email, wallet address, or country code allowed.
required:
- value
WalletAnalytics:
type: object
properties:
totalWallets:
type: integer
embeddedWallets:
type: integer
externalWallets:
type: integer
byChain:
type: object
additionalProperties:
type: integer
Jwks:
type: object
properties:
keys:
type: array
items:
type: object
properties:
kty:
type: string
use:
type: string
kid:
type: string
alg:
type: string
n:
type: string
e:
type: string