Create a policy

You can create a policy using the Privy Dashboard, the NodeJS SDK, or the REST API. Policies optionally have owners, which represent the signatures required to modify the policy after creation, see setting authorization signatures.

We highly recommend specifying owners for your policies to further restrict the parties that can modify them. Without an owner, the policies can be updated by your app secret alone.

NodeJS
NodeJS (server-auth)
Java
Rust
REST API

Use the PrivyClient’s create method from the policies() interface to create a new policy.

const policy = await privy.policies().create({
  name: 'Allow list certain smart contracts',
  version: '1.0',
  chain_type: 'ethereum',
  rules: [
    {
      name: 'Allow list USDC',
      method: 'eth_sendTransaction',
      action: 'ALLOW',
      conditions: [
        {
          field_source: 'ethereum_transaction',
          field: 'to',
          operator: 'eq',
          value: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        }
      ]
    }
  ],
  owner_id: 'fmfdj6yqly31huorjqzq38zc'
});

The @privy-io/server-auth library is deprecated. We recommend integrating @privy-io/node for the latest features and support.

Use the PrivyClient’s createPolicy method to create a new policy.

const policy = await privy.walletApi.createPolicy({
  name: 'Allowlist certain smart contracts',
  version: '1.0',
  chainType: 'ethereum',
  rules: [
    {
      name: 'Allowlist USDC',
      method: 'eth_sendTransaction',
      action: 'ALLOW',
      conditions: [
        {
          fieldSource: 'ethereum_transaction',
          field: 'to',
          operator: 'eq',
          value: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        }
      ]
    }
  ],
  ownerId: 'fmfdj6yqly31huorjqzq38zc'
});

You can create a policy using the Java SDK by using the policies().create() method.

try {
    // Create a policy rule to allow USDC transfers
    PolicyRule allowUsdc = PolicyRule.builder()
        .name("Allowlist USDC")
        .method(PolicyRuleMethod.ETH_SEND_TRANSACTION)
        .action(Action.ALLOW)
        .conditions(List.of(
            EthereumTransactionCondition.builder()
                .fieldSource(EthereumTransactionConditionFieldSource.ETHEREUM_TRANSACTION)
                .field(EthereumTransactionConditionField.TO)
                .operator(ConditionOperator.EQ)
                .value(ConditionValue.of("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"))
                .build()
        ))
        .build();

    // Create a policy that contains your rules
    PolicyCreateRequestBody policy = PolicyCreateRequestBody.builder()
      .version(Version.ONE_DOT0)
      .name("Allowlist certain smart contracts")
      .chainType(PolicyChainType.ETHEREUM)
      .rules(List.of(
          allowUsdc
      ))
      .build();

    PolicyCreateResponse response = privyClient
        .policies()
        .create(policy);

    if (response.policy().isPresent()) {
      Policy policy = response.policy().get();
      String policyId = policy.id();
    }
} catch (APIException e) {
    String errorBody = e.bodyAsString();
    System.err.println(errorBody);
} catch (Exception e) {
    System.err.println(e.getMessage());
}

Parameters

When defining a policy, you may specify the following values on the PolicyCreateRequestBody builder:

Hide parameters

version

Version

Version of the policy.

name

String

Name to assign to policy.

chainType

PolicyChainType

Chain type for wallets that the policy will be applied to.

rules

List<PolicyRule>

A list of Rule objects describing what rules to apply to each RPC method (e.g. 'eth_sendTransaction') that the wallet can take. Learn more about Rules.

owner

OwnerInput

The owner of the policy. You should specify either an owner or an ownerId, but not both.

ownerId

String

The key quorum ID of the owner of the policy. You should specify either an owner or an ownerId, but not both.

Returns

The PolicyCreateResponse object contains an optional policy() field that contains the created policy if the policy was created successfully.

policy()

Optional<Policy>

The created policy.

Hide Policy

version

Version

Version of the policy.

name

String

Name of the policy.

chainType

PolicyChainType

Chain type of the wallets that the policy will be applied to.

String

Unique ID of the policy.

ownerId

String

The key quorum ID of the owner of the policy.

createdAt

Double

The Unix time of when the policy was created.

rules

List<PolicyRule>

A list of Rule objects describing what rules to apply to each RPC method (e.g. 'eth_sendTransaction') that the wallet can take. Learn more about Rules.

Use the PrivyClient’s create method from the policies() interface to create a new policy.

use privy_rs::{PrivyClient, generated::types::*};

let client = PrivyClient::new(app_id, app_secret)?;

// Create policy rules
let usdc_condition = PolicyRuleCondition {
    field_source: "ethereum_transaction".to_string(),
    field: "to".to_string(),
    operator: "eq".to_string(),
    value: serde_json::Value::String("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913".to_string()),
};

let allow_usdc_rule = PolicyRule {
    name: "Allow list USDC".to_string(),
    method: "eth_sendTransaction".to_string(),
    action: PolicyRuleAction::Allow,
    conditions: vec![usdc_condition],
};

let request = CreatePolicyBody {
    name: "Allow list certain smart contracts".to_string(),
    version: "1.0".to_string(),
    chain_type: "ethereum".to_string(),
    rules: vec![allow_usdc_rule],
    owner_id: Some("fmfdj6yqly31huorjqzq38zc".to_string()),
    owner: None,
};

let policy = client
    .policies()
    .create(request, &authorization_context)
    .await?;

println!("Created policy: {}", policy.id);

Parameters and Returns

See the Rust SDK documentation for detailed parameter and return types, including embedded examples:

PoliciesClient::create

For REST API details, see the API reference.

To create a new policy, make a POST request to:

https://api.privy.io/v1/policies

In the request headers, make sure to include Privy’s required authentication headers and headers that may be required for your app’s wallet API setup. You can also include an idempotency key header.

Body

In the request body, include the following:

Hide body attributes

version

'1.0'

Version of the policy. Currently, 1.0 is the only version.

name

string

Name to assign to policy.

chain_type

'ethereum'

Chain type for wallets that the policy will be applied to.

rules

Rule

A list of Rule objects describing what rules to apply to each RPC method (e.g. 'eth_sendTransaction') that the wallet can take. Learn more about Rules.

owner

{public_key: string} | null

The P-256 public key of the owner of the policy. If you provide this, do not specify an owner_id as it will be generated automatically.View this guide to learn more about owners.

owner_id

string | null

The key quorum ID of the owner of the policy. If you provide this, do not specify an owner.View this guide to learn more about owners.

Once you have successfully created a policy, you can assign that policy to a wallet at creation.

Response

If the policy is created successfully, the response will include the request body as well as an additional unique id field for the policy.

Hide response

string

Unique ID for the policy.

version

'1.0'

Version of the policy. Currently, 1.0 is the only version.

name

string

Name to assign to policy.

chain_type

'ethereum'

Chain type for wallets that the policy will be applied to.

rules

Rule[]

A list of Rule objects describing what rules to apply to each RPC method (e.g. 'eth_sendTransaction') that the wallet can take. Learn more about Rules.

owner_id

string | null

The key quorum ID of the owner of the policy, whose signature is required to modify the policy.

Example

As an example, a sample request to create a new eth_sendTransaction policy might look like the following:

$ curl --request POST https://api.privy.io/v1/policies \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H "privy-authorization-signature: <authorization-signature-for-request>" \
-H 'Content-Type: application/json' \
-d '{
    "version": "1.0",
    "name": "Allowlist certain smart contracts",
    "chain_type": "ethereum",
    "rules": [{
      "name": "Allowlist USDC",
      "method": "eth_sendTransaction",
      "conditions": [
          {
              "field_source": "ethereum_transaction",
              "field": "to",
              "operator": "eq",
              "value": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
          }
      ],
      "action": "ALLOW"
    }],
    "owner": {
      "public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEx4aoeD72yykviK+f/ckqE2CItVIG1rCnvC3/XZ1HgpOcMEMialRmTrqIK4oZlYd1RfxU3za/C9yjhboIuoPD3g=="
    }
}'

A successful response will look like the following:

{
  "id": "fmfdj6yqly31huorjqzq38zc",
  "name": "Allowlist certain smart contracts",
  "version": "1.0",
  "chain_type": "ethereum",
  "rules": [
    {
      "name": "Allowlist USDC",
      "method": "eth_sendTransaction",
      "conditions": [
        {
          "field_source": "ethereum_transaction",
          "field": "to",
          "operator": "eq",
          "value": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
        }
      ],
      "action": "ALLOW"
    }
  ],
  "owner_id": "fmfdj6yqly31huorjqzq38zc"
}

Owners & signers

Configuring your wallets

Creating owners & signers

Using owners & signers

Key quorums

Policies

Dashboard controls

Parameters

Returns

Parameters and Returns

Body

Response

Example

Owners & signers

Configuring your wallets

Creating owners & signers

Using owners & signers

Key quorums

Policies

Dashboard controls

​Parameters

​Returns

​Parameters and Returns

​Body

​Response

​Example

Parameters

Returns

Parameters and Returns

Body

Response

Example