Author policies with JSON

Validate, create, and activate advanced permissions policies on a beta API key

Learn how to publish a policy outside the Developer Portal forms. Use the CLI for supported wallet types, nested conditions, personal limits, or approval requirements that you want to author directly as JSON. Contact Para for help checking an advanced policy before relying on it. To start from a working definition, see Guardrail templates and Request templates.

1. Authenticate and select the beta key

   Install the CLI, then authenticate with your developer account. These commands require access to the selected organization and project, not just possession of its public API key.

   para login
   para orgs switch
   para projects switch
   para keys list --environment beta
   para keys permissions state KEY_ID --environment beta --json
   para keys permissions catalog KEY_ID --environment beta --json
   

   Use the key’s ID for KEY_ID. The catalog describes the available authoring language; state returns the current policy records. Use para keys permissions state to manage these policies; the parent command returns a legacy status view.

2. Start with a Solana transfer Request

   Save this document as solana-transfers.json. It asks a user for standing access to native SOL transfers up to 0.01 SOL. 10000000 is an integer amount in lamports, not a dollar amount. actions limits the rule to native transfers, and the asset condition pins the transfer to native SOL.

   solana-transfers.json

   {
     "id": "solana-small-transfers",
     "schemaVersion": "permissions.policy.v1",
     "version": "1",
     "selector": {
       "walletType": "SOLANA"
     },
     "rules": [
       {
         "id": "small-native-transfer",
         "effect": "allow",
         "actions": ["transfer_native"],
         "when": {
           "kind": "all",
           "of": [
             { "kind": "compare", "fact": "request.value.asset", "op": "eq", "value": "solana:native" },
             { "kind": "compare", "fact": "request.value.baseUnits", "op": "lte", "value": "10000000" }
           ]
         }
       }
     ],
     "metadata": {
       "productMode": "delegation",
       "description": "Send up to 0.01 SOL per native transfer"
     }
   }
   

   This selector applies to every Solana wallet under the selected API key. Add walletId to limit it to specific wallets, or chainId (for example "solana:mainnet") to limit it to one network. For an app-owned wallet, design a Guardrail with the appropriate deny/approval rules instead of assuming this user-consent Request has the same meaning.

3. Validate, save, and activate

   para keys permissions validate KEY_ID --file solana-transfers.json --environment beta --json
   para keys permissions create KEY_ID --file solana-transfers.json --environment beta --json
   

   Inspect the validation result and returned draft. Copy the new policy.recordId from the create response, then activate that record:

   para keys permissions activate RECORD_ID KEY_ID --environment beta --yes --json
   para keys permissions state KEY_ID --environment beta --json
   

   To schedule the policy, pass --effective-from <utc-iso> or --effective-until <utc-iso> to create or replace. Without --json, validate, create, and replace print a warning for each active policy that overlaps this one.

   Validation checks the policy against the trusted project/key context. Creating a draft does not enable its behavior. Activation enables policy enforcement and supersedes an active version with the same logical policy ID.

   The CLI accepts advanced JSON, but does not bypass policy validation, organization permissions, or the beta-only mutation boundary. A successful validation is not proof that the policy expresses your intent; test both matching and non-matching requests.

4. Exercise the user flow

   Use the normal Solana signer integration with a user-owned wallet. Grant the Request through Portal, then test an amount below the limit and one above it. The first can use standing access; the second does not receive permission from this rule and follows the remaining policies and review flow.

   Integrate consent and adjustable limits

Update or retire the policy

To replace a policy, keep its id, selector, and metadata.productMode, and set version to the next integer. A different selector is a separate policy, so create it instead. Replacing an active record takes effect immediately; replacing a draft keeps the replacement in draft. Without activation flags, the replacement keeps the current activation window.

para keys permissions replace RECORD_ID KEY_ID --file solana-transfers-updated.json --environment beta --yes --json
para keys permissions deactivate ACTIVE_RECORD_ID KEY_ID --environment beta --yes --json
para keys permissions archive INACTIVE_RECORD_ID KEY_ID --environment beta --yes --json

Read the state again after each change. If a command cannot confirm whether a mutation completed, inspect the current records before retrying. Do not blindly create another version.

Build more complex policies

Manage versions and production review