Access control

This page provides examples of policies governing access generally.

Allow a specific user to create wallets

{
  "policyName": "Allow user <USER_ID> to create wallets",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.id == '<USER_ID>')",
  "condition": "activity.resource == 'WALLET' && activity.action == 'CREATE'"
}

Allow users with a specific tag to create users

{
  "policyName": "Allow user_tag <USER_TAG_ID> to create users",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.tags.contains('<USER_TAG_ID>'))",
  "condition": "activity.resource == 'USER' && activity.action == 'CREATE'"
}

Require two users with a specific tag to add policies

{
  "policyName": "Require two users with user_tag <USER_TAG_ID> to create policies",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.filter(user, user.tags.contains('<USER_TAG_ID>')).count() >= 2",
  "condition": "activity.resource == 'POLICY' && activity.action == 'CREATE'"
}

The filter can match multiple tags: user.tags.contains('<TAG_A>') || user.tags.contains('<TAG_B>') would require two approvers in total from either tag, in any combination. This counts a total; see below for enforcing a separate minimum per tag.

Require multiple approvers across tags, with per-tag minimums

This policy requires at least 1 approver tagged <SECURITY_TAG_ID> and at least 2 approvers tagged <OPS_TAG_ID> to create, update, or delete policies. A user carrying both tags counts toward both minimums.

{
  "policyName": "Require 1 security + 2 ops approvers for policy changes",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.tags.contains('<SECURITY_TAG_ID>') || user.tags.contains('<OPS_TAG_ID>')) && (approvers.filter(user, user.tags.contains('<SECURITY_TAG_ID>')).count() >= 1 && approvers.filter(user, user.tags.contains('<OPS_TAG_ID>')).count() >= 2)",
  "condition": "activity.resource == 'POLICY' && (activity.action == 'CREATE' || activity.action == 'UPDATE' || activity.action == 'DELETE')"
}

Deny all delete actions for users with a specific tag

{
  "policyName": "Only user_tag <USER_TAG_ID> can take actions",
  "effect": "EFFECT_DENY",
  "consensus": "approvers.any(user, user.tags.contains('<USER_TAG_ID>'))",
  "condition": "activity.action == 'DELETE'"
}

Allow a specific user (e.g. API-only user) to create a sub-org

{
  "policyName": "Allow user <USER_ID> to create a sub-org",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.id == '<YOUR_API_USER_ID>')",
  "condition": "activity.resource == 'ORGANIZATION' && activity.action == 'CREATE'"
}

Allow a specific user to perform auth type activities (full list here)

Note: The activity.resource portion determines which activities can be performed. The activity.action determines what types of actions can be taken upon those resources.

{
  "policyName": "Allow user <USER_ID> to initiate auth type activities",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.id == '<YOUR_API_USER_ID>')",
  "condition": "activity.resource == 'AUTH' && activity.action == 'CREATE'"
}

Allow a specific user to perform generic OTP activities

{
  "policyName": "Allow user <USER_ID> to initiate and verify generic OTP activities",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.id == '<YOUR_API_USER_ID>')",
  "condition": "activity.resource in ['AUTH', 'OTP'] && activity.action in ['CREATE','VERIFY']"
}

Allow a specific user to perform a specific activity type (full list here)

Note: Activities may be upgraded over time, and thus new versions may be introduced. These policies will NOT be valid if an activity type is upgraded and requests are made on the new activity type. For example, if Turnkey introduces ACTIVITY_TYPE_CREATE_READ_WRITE_SESSION_V3 (upgraded from ACTIVITY_TYPE_CREATE_READ_WRITE_SESSION_V2) and a request is made with the newer V3 version, this policy with not allow that user to perform ACTIVITY_TYPE_CREATE_READ_WRITE_SESSION_V3 activities.

JSON

{
  "policyName": "Allow user <USER_ID> to perform create read write session v2",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.id == '<YOUR_API_USER_ID>')",
  "condition": "activity.type == 'ACTIVITY_TYPE_CREATE_READ_WRITE_SESSION_V2'"
}

Allow a specific user to perform a specific activity kind (full list here)

Unlike activity.type, which targets one exact version, activity.kind is version-agnostic: a single kind matches every version of an activity. Prefer activity.kind when you want a policy to keep working as activities are upgraded. For example, the policy below continues to allow the user to create read write sessions even if Turnkey introduces a newer version such as ACTIVITY_TYPE_CREATE_READ_WRITE_SESSION_V3, because CREATE_READ_WRITE_SESSION matches all versions.

Not sure whether to use type, kind, or resource + action? See Choosing between type, kind, and resource + action for guidance.

JSON

{
  "policyName": "Allow user <USER_ID> to create read write sessions (any version)",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.id == '<YOUR_API_USER_ID>')",
  "condition": "activity.kind == 'CREATE_READ_WRITE_SESSION'"
}

Allow a specific user to sign transactions across all versions

JSON

{
  "policyName": "Allow user <USER_ID> to sign transactions (any version)",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.id == '<YOUR_API_USER_ID>')",
  "condition": "activity.kind == 'SIGN_TRANSACTION'"
}

Allow a specific credential type to perform a specific action (full list of credential types here)

This policy can be used to say, only passkeys are allowed to sign transactions and not authentication through SMS (or any other authentication method).

JSON

{
  "policyName": "Allow signing with only passkeys",
  "effect": "EFFECT_ALLOW",
  "consensus": "credentials.any(credential, credential.type == 'CREDENTIAL_TYPE_WEBAUTHN_AUTHENTICATOR')",
  "condition": "activity.type == 'ACTIVITY_TYPE_SIGN_TRANSACTION_V2'"
}

Allow a specific credential with a specific public key type to perform a specific action

JSON

{
  "policyName": "Allow signing with only passkeys",
  "effect": "EFFECT_ALLOW",
  "consensus": "credentials.any(credential, credential.public_key == '<YOUR_CREDENTIAL_PUBLIC_KEY>')",
  "condition": "activity.type == 'ACTIVITY_TYPE_SIGN_TRANSACTION_V2'"
}

Allow exporting only a specific wallet account address

JSON

{
  "policyName": "Allow exporting only wallet account <WALLET_ACCOUNT_ADDRESS>",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.id == '<USER_ID>')",
  "condition": "activity.action == 'EXPORT' && wallet_account.address == '<WALLET_ACCOUNT_ADDRESS>'"
}

Allow exporting only wallet accounts under a hardened derivation subtree

This policy allows exporting only wallet accounts whose derivation path is a fully-hardened, 4-segment path of the form m/8797555'/x'/3'/y' (a Spark-purpose subtree). Because single-quoted policy literals cannot contain ' (apostrophe), the path is matched structurally via wallet_account.path_indexes and wallet_account.path_hardened rather than as a string. Note that policies match the literal stored path; on ed25519, soft and hardened spellings derive the same key.

JSON

{
  "policyName": "Allow exporting only accounts under m/8797555'/x'/3'/y'",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.id == '<USER_ID>')",
  "condition": "activity.kind == 'EXPORT_WALLET_ACCOUNT' && wallet_account.path_indexes.count() == 4 && wallet_account.path_indexes[0] == 8797555 && wallet_account.path_indexes[2] == 3 && wallet_account.path_hardened.all(h, h == true)"
}

The derivation-path fields are populated only for EXPORT_WALLET_ACCOUNT activities: on any other activity, a condition referencing them produces an evaluation error (the policy’s outcome is an error, not a match against empty values). Prefer narrow allow policies like this one over combining a broad allow with a path-based EFFECT_DENY: during rollout windows where some Turnkey components do not yet know these fields, an erroring deny is skipped while a broad allow still matches (failing open), whereas a narrow allow that errors fails closed.