Skip to main content

Permissions & Authorization

Manage fee grants and authorization grants to control who pays fees and what operations are allowed.

Overview​

Who pays fees for whom (Fee Grants) and what a key is allowed to do (Authorization Grants / Authz).

What success looks like:​

  • Required fee coverage is present for the grantee that will submit transactions.
  • Authz grants include only the msg_type_urls you expect; expirations in the future.
  • After any Tx, the verify reads reflect the new state.

Authorization & Fee Grants: Read Checks​

Who pays fees; what's allowed. Use these to inspect the current state before/after any write (Tx).

Fee grants​

Pair-specific allowance (granter → grantee) Confirm a fee payer covers a particular grantee.

Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/feegrant/v1beta1/allowance/pb1GRANTER.../pb1GRANTEE..."

SPEC →

All allowances for a grantee

See everything available to a grantee.

Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/feegrant/v1beta1/allowances/pb1GRANTEE..."

SPEC →

All allowances issued by a granter

Audit what a granter has delegated.

Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/feegrant/v1beta1/allowances_by_granter/pb1GRANTER..."

SPEC →

(Plus) UI-friendly fee grants summaries

Show consolidated views and allowed messages in your app.

Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_PLUS_BASE/v1/feegrants/by-grantee/pb1GRANTEE..."

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_PLUS_BASE/v1/feegrants/by-granter/pb1GRANTER..."

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_PLUS_BASE/v1/feegrants/pb1GRANTEE.../allowed-messages"

SPEC →

Authorization Grants (Authz)​

Filterable list Check what a grantee can do (one call; filter by grantee/granter/msg_type_url).

Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/authz/v1beta1/grants?granter=pb1GRANTER...&grantee=pb1GRANTEE..."

SPEC →

Authz by grantee

Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/authz/v1beta1/grants/grantee/pb1GRANTEE..."

SPEC →

Authz by granter

Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/authz/v1beta1/grants/granter/pb1GRANTER..."

SPEC →

Tips: Scope signing grants to exact msg_type_url values, set expirations, and surface allowed messages in your UI.

Write flows (Tx) → Verify​

How to think about it​

  • Fee Grant: Lets A pay transaction fees for B (set per-denom limits & expiration).
  • Authz Grant: Lets B execute a specific message type on behalf of A (least-privilege via msg_type_url; set expiration).
  • Revoke/Update: Remove or tighten previously issued grants.
Code snippet
# Broadcast (RPC) -- choose one per UX (JSON-RPC)

# Sync
curl -X POST "https://pio-mainnet-1-rpc.provlabs.com" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"broadcast_tx_sync","params":["<BASE64_SIGNED_TX>"]}'

# Async
curl -X POST "https://pio-mainnet-1-rpc.provlabs.com" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"broadcast_tx_async","params":["<BASE64_SIGNED_TX>"]}'

# Commit
curl -X POST "https://pio-mainnet-1-rpc.provlabs.com" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"broadcast_tx_commit","params":["<BASE64_SIGNED_TX>"]}'

Note: The "tx" param is the Base64-encoded protobuf bytes of the signed Tx (not JSON).

Before signing: fetch account_number & sequence (account_info), set chain_id, fee/gas, and memo as needed.

Grant Fee Payer (Fee Grant) → Verify​

  1. Build a Fee-Grant Transaction (Vault) Create an unsigned fee-grant transaction that lets a granter pay fees for a grantee. Set at minimum:
    • granter (pb1… address)
    • grantee (pb1… address)
    • allowance / spend limits (e.g., per-denom limits)
    • expiration (RFC3339)

Example unsigned tx (shape) returned by a Vault builder — sign locally, then broadcast via Node RPC. (Structure shown for clarity; exact Vault response fields may differ by module/tenant. Build in Vault; don't POST this to REST.)

Response
{
  "messages": [
    {
      "@type": "/cosmos.feegrant.v1beta1.MsgGrantAllowance",
      "granter": "pb1GRANTER...",
      "grantee": "pb1GRANTEE...",
      "allowance": {
        "@type": "/cosmos.feegrant.v1beta1.BasicAllowance",
        "spend_limit": [{ "denom": "nhash", "amount": "1000000000" }],
        "expiration": "2025-12-31T23:59:59Z"
      }
    }
  ]
}

SPEC →

  1. Sign & Broadcast (Node RPC): use one of broadcast_tx_sync | broadcast_tx_async | broadcast_tx_commit (see Broadcast (RPC) above). After the transaction is included in a block, verify the grant:
    • broadcast_tx_sync: Quick feedback after CheckTx.
    • broadcast_tx_async: Fire-and-forget.
    • broadcast_tx_commit: Waits for block inclusion (slowest, but most final).
  2. Verify (Reads) After the transaction is included in a block, verify the grant:
Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/feegrant/v1beta1/allowance/pb1GRANTER.../pb1GRANTEE..."

Optional UI Summary:

Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_PLUS_BASE/v1/feegrants/by-grantee/pb1GRANTEE..."

Grant Signing Permission (Authz) → Verify​

  1. Build an Authz Grant Transaction (Vault) Create an unsigned authorization grant so a grantee can execute a specific message type on behalf of a granter. Set at minimum:
    • granter (pb1… address)
    • grantee (pb1… address)
    • msg_type_url (exact message type you want to allow, e.g., /cosmos.bank.v1beta1.MsgSend)
    • expiration (RFC3339)

Example unsigned tx (shape) returned by a Vault builder: sign locally, then broadcast via Node RPC. Structure shown for clarity; exact Vault response fields may differ by module/tenant. Build in Vault; don't POST this to REST.

Response
{
  "messages": [
    {
      "@type": "/cosmos.authz.v1beta1.MsgGrant",
      "granter": "pb1GRANTER...",
      "grantee": "pb1GRANTEE...",
      "grant": {
        "authorization": {
          "@type": "/cosmos.authz.v1beta1.GenericAuthorization",
          "msg": "/cosmos.bank.v1beta1.MsgSend"
        },
        "expiration": "2025-12-31T23:59:59Z"
      }
    }
  ]
}

SPEC →

  1. Sign & Broadcast (Node RPC): use one of broadcast_tx_sync | broadcast_tx_async | broadcast_tx_commit (see Broadcast (RPC) above). Use the same broadcast options as Fee Grant.
  2. Verify (Reads) Confirm the grant exists:
Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/authz/v1beta1/grants?grantee=pb1GRANTEE...&msg_type_url=/cosmos.bank.v1beta1.MsgSend"

Revoke or Update a Grant → Verify​

Build Revoke/Update Transaction (Vault) Create an unsigned transaction to revoke or adjust an existing grant.

Fee Grant Revoke/Update: Example unsigned tx (shape) returned by a Vault builder — sign locally, then broadcast via Node RPC.

Response
{
  "messages": [
    {
      "@type": "/cosmos.feegrant.v1beta1.MsgRevokeAllowance",
      "granter": "pb1GRANTER...",
      "grantee": "pb1GRANTEE..."
    }
  ]
}

Authz Grant Revoke/Update:

Response
{
  "messages": [
    {
      "@type": "/cosmos.authz.v1beta1.MsgRevoke",
      "granter": "pb1GRANTER...",
      "grantee": "pb1GRANTEE...",
      "msg_type_url": "/cosmos.bank.v1beta1.MsgSend"
    }
  ]
}
  1. Sign & Broadcast (Node RPC): use one of broadcast_tx_sync | broadcast_tx_async | broadcast_tx_commit (see Broadcast (RPC) above). Use the same broadcast options as Fee Grant.
  2. Verify (Reads)

Fee Grant: Ensure the pair is absent after revocation:

Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/feegrant/v1beta1/allowance/pb1GRANTER.../pb1GRANTEE..."

Authz Grant: Ensure no result for the msg_type_url after revocation:

Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/authz/v1beta1/grants?grantee=pb1GRANTEE...&msg_type_url=/cosmos.bank.v1beta1.MsgSend"