> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Authz

> gRPC queries and transaction messages defined by the authz module in Cosmos SDK v0.55 (unreleased).

<Info>
  Generated from [`cosmos/cosmos-sdk@c1126e4e5460`](https://github.com/cosmos/cosmos-sdk/tree/c1126e4e5460571378bf9bd9c49cce476b0791e2/proto) on ref `main`.
</Info>

## Queries

A node exposes only the services its application registers:

* gRPC on port 9090
* REST on port 1317, if the method has an HTTP binding

Run `grpcurl -plaintext localhost:9090 list` to see what a node serves.

Queries are read-only and never pass through consensus. See [Queries](/sdk/next/learn/concepts/transactions#queries).

Replace `<string>` placeholders with real values and omit unused filters. Payloads use protobuf JSON, and some `string` fields accept enum constants listed under Types. Field tables give the encoding each value takes.

Examples assume a local node. For TLS endpoints, use port 443 and omit `-plaintext`. See [gRPC services](/sdk/next/api-reference/grpc/index) for reflection, address formats, and decimal encoding.

### GranteeGrants

GranteeGrants returns a list of `GrantAuthorization` by grantee.

| | |
| - | - |
| gRPC | `cosmos.authz.v1beta1.Query/GranteeGrants` |
| REST | `GET /cosmos/authz/v1beta1/grants/grantee/{grantee}` |

Request `QueryGranteeGrantsRequest`:

| Field | Type | Description |
| - | - | - |
| `grantee` | `string` | Encoded as cosmos.AddressString. |
| `pagination` | [`PageRequest`](#cosmos-base-query-v1beta1-pagerequest) | pagination defines a pagination for the request. |

Response `QueryGranteeGrantsResponse`:

| Field | Type | Description |
| - | - | - |
| `grants` | [`GrantAuthorization`](#cosmos-authz-v1beta1-grantauthorization)\[] | grants is a list of grants granted to the grantee. |
| `pagination` | [`PageResponse`](#cosmos-base-query-v1beta1-pageresponse) | pagination defines a pagination for the response. |

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"grantee":"<string>","pagination":{"limit":"1"}}' \
  localhost:9090 cosmos.authz.v1beta1.Query/GranteeGrants
```

### GranterGrants

GranterGrants returns list of `GrantAuthorization`, granted by granter.

| | |
| - | - |
| gRPC | `cosmos.authz.v1beta1.Query/GranterGrants` |
| REST | `GET /cosmos/authz/v1beta1/grants/granter/{granter}` |

Request `QueryGranterGrantsRequest`:

| Field | Type | Description |
| - | - | - |
| `granter` | `string` | Encoded as cosmos.AddressString. |
| `pagination` | [`PageRequest`](#cosmos-base-query-v1beta1-pagerequest) | pagination defines a pagination for the request. |

Response `QueryGranterGrantsResponse`:

| Field | Type | Description |
| - | - | - |
| `grants` | [`GrantAuthorization`](#cosmos-authz-v1beta1-grantauthorization)\[] | grants is a list of grants granted by the granter. |
| `pagination` | [`PageResponse`](#cosmos-base-query-v1beta1-pageresponse) | pagination defines a pagination for the response. |

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"granter":"<string>","pagination":{"limit":"1"}}' \
  localhost:9090 cosmos.authz.v1beta1.Query/GranterGrants
```

### Grants

Returns list of `Authorization`, granted to the grantee by the granter.

| | |
| - | - |
| gRPC | `cosmos.authz.v1beta1.Query/Grants` |
| REST | `GET /cosmos/authz/v1beta1/grants` |

Request `QueryGrantsRequest`:

| Field | Type | Description |
| - | - | - |
| `granter` | `string` | Encoded as cosmos.AddressString. |
| `grantee` | `string` | Encoded as cosmos.AddressString. |
| `msg_type_url` | `string` | Optional, msg\_type\_url, when set, will query only grants matching given msg type. |
| `pagination` | [`PageRequest`](#cosmos-base-query-v1beta1-pagerequest) | pagination defines a pagination for the request. |

Response `QueryGrantsResponse`:

| Field | Type | Description |
| - | - | - |
| `grants` | [`Grant`](#cosmos-authz-v1beta1-grant)\[] | authorizations is a list of grants granted for grantee by granter. |
| `pagination` | [`PageResponse`](#cosmos-base-query-v1beta1-pageresponse) | pagination defines a pagination for the response. |

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext -d '{"granter":"<string>","grantee":"<string>","msg_type_url":"<string>","pagination":{"limit":"1"}}' \
  localhost:9090 cosmos.authz.v1beta1.Query/Grants
```

## Transaction messages

These messages are included in signed transactions, not called as endpoints. See [Transactions](/sdk/next/learn/concepts/transactions#transactions) for the execution model, and [Sending transactions](/sdk/next/api-reference/transactions) for the envelope they go into.

Examples use CLI transaction JSON. Decimal fields use values such as `"0.05"`, even when their proto type is `bytes`. The gRPC `TxEncode` method instead requires the scaled value `"50000000000000000"`. See [scalar encodings](/sdk/next/api-reference/grpc/index#scalar-encodings).

* Handler: Generated client method
* Signer: Account that must sign
* Amino name: Legacy identifier used by hardware wallets and other Amino signers

### Exec

Exec attempts to execute the provided messages using authorizations granted to the grantee. Each message should have only one signer corresponding to the granter of the authorization.

| | |
| - | - |
| Type URL | `/cosmos.authz.v1beta1.MsgExec` |
| Handler | `cosmos.authz.v1beta1.Msg/Exec` |
| Signer | `grantee` |
| Amino name | `cosmos-sdk/MsgExec` |

| Field | Type | Description |
| - | - | - |
| `grantee` | `string` | Encoded as cosmos.AddressString. |
| `msgs` | `Any`\[] | Execute Msg. The x/authz will try to find a grant matching (msg.signers\[0], grantee, MsgTypeURL(msg)) triple and validate it. Accepts any message implementing cosmos.base.v1beta1.Msg. |

In a transaction:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "@type": "/cosmos.authz.v1beta1.MsgExec",
  "grantee": "<string>",
  "msgs": [
    {
      "@type": "/cosmos.example.v1.MsgExample",
      "...": "the fields of that message, inline"
    }
  ]
}
```

Response `MsgExecResponse`:

| Field | Type | Description |
| - | - | - |
| `results` | `bytes`\[] | |

### Grant

Grant grants the provided authorization to the grantee on the granter's account with the provided expiration time. If there is already a grant for the given (granter, grantee, Authorization) triple, then the grant will be overwritten.

| | |
| - | - |
| Type URL | `/cosmos.authz.v1beta1.MsgGrant` |
| Handler | `cosmos.authz.v1beta1.Msg/Grant` |
| Signer | `granter` |
| Amino name | `cosmos-sdk/MsgGrant` |

| Field | Type | Description |
| - | - | - |
| `granter` | `string` | Encoded as cosmos.AddressString. |
| `grantee` | `string` | Encoded as cosmos.AddressString. |
| `grant` | [`Grant`](#cosmos-authz-v1beta1-grant) | |

In a transaction:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "@type": "/cosmos.authz.v1beta1.MsgGrant",
  "granter": "<string>",
  "grantee": "<string>",
  "grant": {
    "authorization": {
      "@type": "/cosmos.example.v1.MsgExample",
      "...": "the fields of that message, inline"
    },
    "expiration": "<RFC 3339 timestamp>"
  }
}
```

Response `MsgGrantResponse`:

This message has no fields.

### Revoke

Revoke revokes any authorization corresponding to the provided method name on the granter's account that has been granted to the grantee.

| | |
| - | - |
| Type URL | `/cosmos.authz.v1beta1.MsgRevoke` |
| Handler | `cosmos.authz.v1beta1.Msg/Revoke` |
| Signer | `granter` |
| Amino name | `cosmos-sdk/MsgRevoke` |

| Field | Type | Description |
| - | - | - |
| `granter` | `string` | Encoded as cosmos.AddressString. |
| `grantee` | `string` | Encoded as cosmos.AddressString. |
| `msg_type_url` | `string` | |

In a transaction:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "@type": "/cosmos.authz.v1beta1.MsgRevoke",
  "granter": "<string>",
  "grantee": "<string>",
  "msg_type_url": "<string>"
}
```

Response `MsgRevokeResponse`:

This message has no fields.

## Types

Messages referenced by the fields above. Protocol buffers version 3 has no required fields, so every field is optional on the wire, and a `[]` suffix marks a repeated field.

### cosmos.authz.v1beta1.Grant

Grant gives permissions to execute the provide method with expiration time.

| Field | Type | Description |
| - | - | - |
| `authorization` | `Any` | One of: `/cosmos.authz.v1beta1.GenericAuthorization`, `/cosmos.bank.v1beta1.SendAuthorization`, `/cosmos.staking.v1beta1.StakeAuthorization`. |
| `expiration` | `Timestamp` | time when the grant will expire and will be pruned. If null, then the grant doesn't have a time expiration (other conditions  in `authorization` may apply to invalidate the grant) |

### cosmos.authz.v1beta1.GrantAuthorization

GrantAuthorization extends a grant with both the addresses of the grantee and granter. It is used in genesis.proto and query.proto

| Field | Type | Description |
| - | - | - |
| `granter` | `string` | Encoded as cosmos.AddressString. |
| `grantee` | `string` | Encoded as cosmos.AddressString. |
| `authorization` | `Any` | One of: `/cosmos.authz.v1beta1.GenericAuthorization`, `/cosmos.bank.v1beta1.SendAuthorization`, `/cosmos.staking.v1beta1.StakeAuthorization`. |
| `expiration` | `Timestamp` | |

### cosmos.base.query.v1beta1.PageRequest

PageRequest is to be embedded in gRPC request messages for efficient pagination. Ex:

`message SomeRequest { Foo some_parameter = 1; PageRequest pagination = 2; }`

| Field | Type | Description |
| - | - | - |
| `key` | `bytes` | key is a value returned in PageResponse.next\_key to begin querying the next page most efficiently. Only one of offset or key should be set. |
| `offset` | `uint64` | offset is a numeric offset that can be used when key is unavailable. It is less efficient than using key. Only one of offset or key should be set. |
| `limit` | `uint64` | limit is the total number of results to be returned in the result page. If left empty it will default to a value to be set by each app. |
| `count_total` | `bool` | count\_total is set to true  to indicate that the result set should include a count of the total number of items available for pagination in UIs. count\_total is only respected when offset is used. It is ignored when key is set. |
| `reverse` | `bool` | reverse is set to true if results are to be returned in the descending order. |

### cosmos.base.query.v1beta1.PageResponse

PageResponse is to be embedded in gRPC response messages where the corresponding request message has used PageRequest.

`message SomeResponse { repeated Bar results = 1; PageResponse page = 2; }`

| Field | Type | Description |
| - | - | - |
| `next_key` | `bytes` | next\_key is the key to be passed to PageRequest.key to query the next page most efficiently. It will be empty if there are no more results. |
| `total` | `uint64` | total is total number of results available if PageRequest.count\_total was set, its value is undefined otherwise |