Skip to content

Add documentation for activity.kind policy enum #718

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
omkarshanbhag wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add documentation for activity.kind policy enum #718

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions features/policies/examples/access-control.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,35 @@ and a request is made with the newer `V3` version, this policy with not allow th
}
```

#### Allow a specific user to perform a specific activity kind (full list [here](/features/policies/language#activity-kinds))

@andrewkmin andrewkmin Jun 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's worth mentioning guidance on this vs. resource + action as well -- lots of ways to skin the cat now (each nuanced)


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.

```json 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 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](/features/users/credentials#credential-types))

This policy can be used to say, only passkeys are allowed to sign transactions and not authentication through SMS (or any other authentication method).
Expand Down
108 changes: 108 additions & 0 deletions features/policies/language.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,7 @@ The language is strongly typed which makes policies easy to author and maintain.
| | credential_id | string | The credential ID of a passkey. Note: this is only populated for passkeys (also known as Authenticators within Turnkey resources), not API keys |
| | public_key | string | The public key of the credential that approved the request |
| **Activity** | type | string | The type of the activity (e.g. ACTIVITY_TYPE_SIGN_TRANSACTION_V2) |
| | kind | string | A version-agnostic grouping of the activity type. Unlike `type`, a single `kind` matches every version of an activity (e.g. `SIGN_TRANSACTION` matches both `ACTIVITY_TYPE_SIGN_TRANSACTION` and `ACTIVITY_TYPE_SIGN_TRANSACTION_V2`). Example values: `SIGN_TRANSACTION`, `CREATE_API_KEYS`, `CREATE_WALLET`, `CREATE_READ_WRITE_SESSION`. See [Activity kinds](#activity-kinds) for the full list of valid values and the kind → activity type mapping. |
| | resource | string | The resource type the activity targets: `USER`, `PRIVATE_KEY`, `POLICY`, `WALLET`, `ORGANIZATION`, `INVITATION`, `CREDENTIAL`, `CONFIG`, `**RECOVERY`, `AUTH`, `OTP`, `PAYMENT_METHOD`, `SUBSCRIPTION` |
| | action | string | The action of the activity: `CREATE`, `UPDATE`, `DELETE`, `SIGN`, `EXPORT`, `IMPORT` |
| | params | struct | The parameters of the activity. See [here](#activity-parameters) for more details. |
Expand Down Expand Up @@ -314,6 +315,113 @@ The language is strongly typed which makes policies easy to author and maintain.

<Note> ** Legacy features, deprecated in the latest SDKs. </Note>

### Activity kinds

@andrewkmin andrewkmin Jun 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an area that needs to be updated with every activity update. I think we need something on the process side, particularly in mono, that flags that this exists and to not neglect it. I'd recommend updating the mono PR description, updating its AGENTS.md file(s), creating a Valet skill, or some combination of these.


`activity.kind` groups all versions of an activity under one version-agnostic value. The table
below lists each kind and the activity types it matches.

| Kind | Matches Activity Types |
| ---- | ---------------------- |
| DELETE_ORGANIZATION | ACTIVITY_TYPE_DELETE_ORGANIZATION |
| CREATE_SUB_ORGANIZATION | ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION, ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V2, ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V3, ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V4, ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V5, ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V6, ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V7, ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V8 |
| DELETE_SUB_ORGANIZATION | ACTIVITY_TYPE_DELETE_SUB_ORGANIZATION |
| CREATE_INVITATIONS | ACTIVITY_TYPE_CREATE_INVITATIONS |
| DELETE_INVITATION | ACTIVITY_TYPE_DELETE_INVITATION |
| CREATE_USERS | ACTIVITY_TYPE_CREATE_USERS, ACTIVITY_TYPE_CREATE_USERS_V2, ACTIVITY_TYPE_CREATE_USERS_V3, ACTIVITY_TYPE_CREATE_USERS_V4 |
| CREATE_API_ONLY_USERS | ACTIVITY_TYPE_CREATE_API_ONLY_USERS |
| CREATE_USER_TAG | ACTIVITY_TYPE_CREATE_USER_TAG |
| UPDATE_USER | ACTIVITY_TYPE_UPDATE_USER |
| UPDATE_USER_NAME | ACTIVITY_TYPE_UPDATE_USER_NAME |
| UPDATE_USER_EMAIL | ACTIVITY_TYPE_UPDATE_USER_EMAIL |
| UPDATE_USER_PHONE_NUMBER | ACTIVITY_TYPE_UPDATE_USER_PHONE_NUMBER |
| UPDATE_USER_TAG | ACTIVITY_TYPE_UPDATE_USER_TAG |
| DELETE_USERS | ACTIVITY_TYPE_DELETE_USERS |
| DELETE_USER_TAGS | ACTIVITY_TYPE_DELETE_USER_TAGS |
| ENABLE_AUTH_PROXY | ACTIVITY_TYPE_ENABLE_AUTH_PROXY |
| DISABLE_AUTH_PROXY | ACTIVITY_TYPE_DISABLE_AUTH_PROXY |
| CREATE_AUTHENTICATORS | ACTIVITY_TYPE_CREATE_AUTHENTICATORS, ACTIVITY_TYPE_CREATE_AUTHENTICATORS_V2 |
| CREATE_API_KEYS | ACTIVITY_TYPE_CREATE_API_KEYS, ACTIVITY_TYPE_CREATE_API_KEYS_V2 |
| DELETE_AUTHENTICATORS | ACTIVITY_TYPE_DELETE_AUTHENTICATORS |
| DELETE_API_KEYS | ACTIVITY_TYPE_DELETE_API_KEYS |
| CREATE_OAUTH_PROVIDERS | ACTIVITY_TYPE_CREATE_OAUTH_PROVIDERS, ACTIVITY_TYPE_CREATE_OAUTH_PROVIDERS_V2 |
| DELETE_OAUTH_PROVIDERS | ACTIVITY_TYPE_DELETE_OAUTH_PROVIDERS |
| CREATE_PRIVATE_KEYS | ACTIVITY_TYPE_CREATE_PRIVATE_KEYS, ACTIVITY_TYPE_CREATE_PRIVATE_KEYS_V2 |
| CREATE_PRIVATE_KEY_TAG | ACTIVITY_TYPE_CREATE_PRIVATE_KEY_TAG |
| UPDATE_PRIVATE_KEY_TAG | ACTIVITY_TYPE_UPDATE_PRIVATE_KEY_TAG |
| DISABLE_PRIVATE_KEY | ACTIVITY_TYPE_DISABLE_PRIVATE_KEY |
| DELETE_PRIVATE_KEY_TAGS | ACTIVITY_TYPE_DELETE_PRIVATE_KEY_TAGS |
| INIT_IMPORT_PRIVATE_KEY | ACTIVITY_TYPE_INIT_IMPORT_PRIVATE_KEY |
| IMPORT_PRIVATE_KEY | ACTIVITY_TYPE_IMPORT_PRIVATE_KEY |
| DELETE_PRIVATE_KEYS | ACTIVITY_TYPE_DELETE_PRIVATE_KEYS |
| SIGN_TRANSACTION | ACTIVITY_TYPE_SIGN_TRANSACTION, ACTIVITY_TYPE_SIGN_TRANSACTION_V2 |
| SIGN_RAW_PAYLOAD | ACTIVITY_TYPE_SIGN_RAW_PAYLOAD, ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2 |
| SIGN_RAW_PAYLOADS | ACTIVITY_TYPE_SIGN_RAW_PAYLOADS |
| SPARK_SIGN_FROST | ACTIVITY_TYPE_SPARK_SIGN_FROST |
| SPARK_PREPARE_TRANSFER | ACTIVITY_TYPE_SPARK_PREPARE_TRANSFER |
| SPARK_CLAIM_TRANSFER | ACTIVITY_TYPE_SPARK_CLAIM_TRANSFER |
| SPARK_PREPARE_LIGHTNING_RECEIVE | ACTIVITY_TYPE_SPARK_PREPARE_LIGHTNING_RECEIVE |
| ETH_SEND_TRANSACTION | ACTIVITY_TYPE_ETH_SEND_TRANSACTION, ACTIVITY_TYPE_ETH_SEND_TRANSACTION_V2 |
| SOL_SEND_TRANSACTION | ACTIVITY_TYPE_SOL_SEND_TRANSACTION |
| EXPORT_PRIVATE_KEY | ACTIVITY_TYPE_EXPORT_PRIVATE_KEY |
| CREATE_WALLET | ACTIVITY_TYPE_CREATE_WALLET |
| CREATE_WALLET_ACCOUNTS | ACTIVITY_TYPE_CREATE_WALLET_ACCOUNTS |
| EXPORT_WALLET | ACTIVITY_TYPE_EXPORT_WALLET |
| EXPORT_WALLET_ACCOUNT | ACTIVITY_TYPE_EXPORT_WALLET_ACCOUNT |
| INIT_IMPORT_WALLET | ACTIVITY_TYPE_INIT_IMPORT_WALLET |
| IMPORT_WALLET | ACTIVITY_TYPE_IMPORT_WALLET |
| DELETE_WALLETS | ACTIVITY_TYPE_DELETE_WALLETS |
| UPDATE_WALLET | ACTIVITY_TYPE_UPDATE_WALLET |
| DELETE_WALLET_ACCOUNTS | ACTIVITY_TYPE_DELETE_WALLET_ACCOUNTS |
| INIT_FIAT_ON_RAMP | ACTIVITY_TYPE_INIT_FIAT_ON_RAMP |
| CREATE_FIAT_ON_RAMP_CREDENTIAL | ACTIVITY_TYPE_CREATE_FIAT_ON_RAMP_CREDENTIAL |
| DELETE_FIAT_ON_RAMP_CREDENTIAL | ACTIVITY_TYPE_DELETE_FIAT_ON_RAMP_CREDENTIAL |
| UPDATE_FIAT_ON_RAMP_CREDENTIAL | ACTIVITY_TYPE_UPDATE_FIAT_ON_RAMP_CREDENTIAL |
| CREATE_POLICY | ACTIVITY_TYPE_CREATE_POLICY, ACTIVITY_TYPE_CREATE_POLICY_V2, ACTIVITY_TYPE_CREATE_POLICY_V3 |
| CREATE_POLICIES | ACTIVITY_TYPE_CREATE_POLICIES |
| UPDATE_POLICY | ACTIVITY_TYPE_UPDATE_POLICY, ACTIVITY_TYPE_UPDATE_POLICY_V2 |
| DELETE_POLICY | ACTIVITY_TYPE_DELETE_POLICY |
| DELETE_POLICIES | ACTIVITY_TYPE_DELETE_POLICIES |
| ACTIVATE_BILLING_TIER | ACTIVITY_TYPE_ACTIVATE_BILLING_TIER |
| SET_PAYMENT_METHOD | ACTIVITY_TYPE_SET_PAYMENT_METHOD, ACTIVITY_TYPE_SET_PAYMENT_METHOD_V2 |
| DELETE_PAYMENT_METHOD | ACTIVITY_TYPE_DELETE_PAYMENT_METHOD |
| UPDATE_ALLOWED_ORIGINS | ACTIVITY_TYPE_UPDATE_ALLOWED_ORIGINS |
| CREATE_WEBHOOK_ENDPOINT | ACTIVITY_TYPE_CREATE_WEBHOOK_ENDPOINT |
| UPDATE_WEBHOOK_ENDPOINT | ACTIVITY_TYPE_UPDATE_WEBHOOK_ENDPOINT |
| DELETE_WEBHOOK_ENDPOINT | ACTIVITY_TYPE_DELETE_WEBHOOK_ENDPOINT |
| INIT_USER_EMAIL_RECOVERY | ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY, ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY_V2 |
| EMAIL_AUTH | ACTIVITY_TYPE_EMAIL_AUTH, ACTIVITY_TYPE_EMAIL_AUTH_V2, ACTIVITY_TYPE_EMAIL_AUTH_V3 |
| INIT_OTP_AUTH | ACTIVITY_TYPE_INIT_OTP_AUTH, ACTIVITY_TYPE_INIT_OTP_AUTH_V2, ACTIVITY_TYPE_INIT_OTP_AUTH_V3 |
| OTP_AUTH | ACTIVITY_TYPE_OTP_AUTH |
| OAUTH | ACTIVITY_TYPE_OAUTH |
| CREATE_READ_WRITE_SESSION | ACTIVITY_TYPE_CREATE_READ_WRITE_SESSION, ACTIVITY_TYPE_CREATE_READ_WRITE_SESSION_V2 |
| OAUTH_LOGIN | ACTIVITY_TYPE_OAUTH_LOGIN |
| OTP_LOGIN | ACTIVITY_TYPE_OTP_LOGIN, ACTIVITY_TYPE_OTP_LOGIN_V2 |
| STAMP_LOGIN | ACTIVITY_TYPE_STAMP_LOGIN |
| UPDATE_AUTH_PROXY_CONFIG | ACTIVITY_TYPE_UPDATE_AUTH_PROXY_CONFIG |
| CREATE_OAUTH2_CREDENTIAL | ACTIVITY_TYPE_CREATE_OAUTH2_CREDENTIAL |
| UPDATE_OAUTH2_CREDENTIAL | ACTIVITY_TYPE_UPDATE_OAUTH2_CREDENTIAL |
| DELETE_OAUTH2_CREDENTIAL | ACTIVITY_TYPE_DELETE_OAUTH2_CREDENTIAL |
| OAUTH2_AUTHENTICATE | ACTIVITY_TYPE_OAUTH2_AUTHENTICATE |
| INIT_OTP | ACTIVITY_TYPE_INIT_OTP, ACTIVITY_TYPE_INIT_OTP_V2, ACTIVITY_TYPE_INIT_OTP_V3 |
| VERIFY_OTP | ACTIVITY_TYPE_VERIFY_OTP, ACTIVITY_TYPE_VERIFY_OTP_V2 |
| CREATE_SMART_CONTRACT_INTERFACE | ACTIVITY_TYPE_CREATE_SMART_CONTRACT_INTERFACE |
| DELETE_SMART_CONTRACT_INTERFACE | ACTIVITY_TYPE_DELETE_SMART_CONTRACT_INTERFACE |
| UPSERT_GAS_USAGE_CONFIG | ACTIVITY_TYPE_UPSERT_GAS_USAGE_CONFIG |
| CREATE_TVC_APP | ACTIVITY_TYPE_CREATE_TVC_APP |
| CREATE_TVC_DEPLOYMENT | ACTIVITY_TYPE_CREATE_TVC_DEPLOYMENT |
| CREATE_TVC_MANIFEST_APPROVALS | ACTIVITY_TYPE_CREATE_TVC_MANIFEST_APPROVALS |
| UPDATE_TVC_APP_LIVE_DEPLOYMENT | ACTIVITY_TYPE_UPDATE_TVC_APP_LIVE_DEPLOYMENT |
| DELETE_TVC_DEPLOYMENT | ACTIVITY_TYPE_DELETE_TVC_DEPLOYMENT |
| DELETE_TVC_APP_AND_DEPLOYMENTS | ACTIVITY_TYPE_DELETE_TVC_APP_AND_DEPLOYMENTS |
| RESTORE_TVC_DEPLOYMENT | ACTIVITY_TYPE_RESTORE_TVC_DEPLOYMENT |
| POST_TVC_QUORUM_KEY_SHARE | ACTIVITY_TYPE_POST_TVC_QUORUM_KEY_SHARE |

Comment on lines +417 to +418
<Note>
Prefer `activity.kind` over `activity.type` when you want a policy to apply across all versions
of an activity. `activity.type` targets one exact version and will not match newer versions
introduced later.
</Note>

## Appendix

### Policy evaluation
Expand Down