Sign in
API Keys

Create API key

Creates a new API key. The full key is returned once.

post/v1/api-keys

Headers

x-project-idstring

Selects the active project for this request. Required for session/dashboard callers. Ignored when authenticating with an API key, whose scope is fixed to the key's project.

Example:prj_example

Selects the active project for this request. Required for session/dashboard callers. Ignored when authenticating with an API key, whose scope is fixed to the key's project.

Request body

namestring required

Friendly name for the API key.

descriptionstring

Optional key description.

role'api_admin' | 'api_developer' | 'api_readonly'

Role assigned to this API key.

permissionsstring[]

Optional explicit permission set. Requires admin access.

walletScope'all' | 'selected' required

Explicit wallet access mode. Use 'all' to allow every wallet in scope or 'selected' to bind specific wallets.

allowedIpsstring[]

Optional list of IPv4/IPv6 addresses or CIDR ranges allowed to use the key.

expiresAtstring date-time

Optional expiration timestamp.

signingWalletIdstring

Optional default custody wallet ID to bind this key to.

signingWalletIdsstring[]

Optional list of custody wallet IDs to bind to this key. The first wallet becomes default unless signingWalletId is explicitly set.

provisionWalletboolean

If true, provisions a new custody wallet and binds it to the key.

walletLabelstring

Optional label for a provisioned wallet.

walletPurpose'root' | 'mint_authority' | 'freeze_authority' | 'fee_payer' | 'transfer'

Optional purpose for a provisioned wallet.

Example request

{
  "name": "Primary Key",
  "description": "Used by backend service.",
  "role": "api_developer",
  "permissions": [
    "tokens:read",
    "tokens:write"
  ],
  "walletScope": "selected",
  "allowedIps": [
    "203.0.113.0/24"
  ],
  "expiresAt": "2025-12-31T00:00:00.000Z",
  "signingWalletId": "privy_wallet_123",
  "signingWalletIds": [
    "privy_wallet_123",
    "dfns_wallet_456"
  ],
  "walletLabel": "Mint authority wallet",
  "walletPurpose": "mint_authority"
}

Response

API key created

Example response

{
  "data": {
    "apiKey": {
      "id": "key_example",
      "name": "Primary Key",
      "key": "sk_test_example",
      "keyPrefix": "sk_test_abc",
      "role": "api_developer",
      "environment": "sandbox",
      "expiresAt": "2025-12-31T00:00:00.000Z",
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  },
  "meta": {
    "requestId": "req_example",
    "timestamp": "2025-01-01T00:00:00.000Z"
  }
}

Changes