> ## 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.
Generated from [`cosmos/cosmos-sdk@2086680ff8b0`](https://github.com/cosmos/cosmos-sdk/tree/2086680ff8b08fd269ee653e087ea577bab79534/proto) on ref `release/v0.55.x`.
## 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/latest/learn/concepts/transactions#queries).
Replace `` 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/latest/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":"","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":"","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":"","grantee":"","msg_type_url":"","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/latest/learn/concepts/transactions#transactions) for the execution model, and [Sending transactions](/sdk/latest/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/latest/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": "",
"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": "",
"grantee": "",
"grant": {
"authorization": {
"@type": "/cosmos.example.v1.MsgExample",
"...": "the fields of that message, inline"
},
"expiration": ""
}
}
```
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": "",
"grantee": "",
"msg_type_url": ""
}
```
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 |