Custom authorisations for IXO Claims

How an authz grant is stored on chain, the three built-in Cosmos SDK authorisation types, the four IXO types for claim messages, and why constraints are lists.

Authorisation (authz) on IXO follows the Cosmos SDK's authz module (ADR 30). It lets one account, the granter, give specific privileges to another account, the grantee. IXO adds its own authorisation types for the messages of the Claims module.

Read this page before you grant an agent the right to submit claims, evaluate claims or withdraw payments. It explains how a grant is stored, which authorisation types exist, and the rules to remember when you grant, query and revoke.

How a grant is stored

Each authorisation is stored on chain with three key components:

{
  "granter": "address",
  "grantee": "address",
  "msg_type_url": "message_type"
}

So there can be only one authorisation for a specific message type between any two accounts. A new authorisation for the same message type between the same accounts overrides the previous one.

Authorisations are implemented with the Authorization interface, which allows the parameters and limits of a grant to be customised. The most basic implementation is GenericAuthorization, which gives unlimited rights to execute a specific message type.

Built-in authorisation types

The Cosmos SDK provides three built-in implementations.

TypeWhat it allows
GenericAuthorizationUnlimited rights to execute a specific message type, with no restrictions
SendAuthorizationSending tokens within specific limits (amount restrictions), for the /cosmos.bank.v1beta1.MsgSend message type
StakeAuthorizationStaking-related operations, with specific parameters

IXO authorisation types for claims

IXO implements custom authorisation types for specific message types.

TypeMessage typeAuthorises
SubmitClaimAuthorization/ixo.claims.v1beta1.MsgSubmitClaimSubmitting claims
EvaluateClaimAuthorization/ixo.claims.v1beta1.MsgEvaluateClaimEvaluating claims
WithdrawPaymentAuthorization/ixo.claims.v1beta1.MsgWithdrawPaymentWithdrawing payments
CreateClaimAuthorization/ixo.claims.v1beta1.MsgCreateClaimAuthorizationCreating claims

Constraints are lists

The IXO types hold their constraints as lists, because there can be only one grant between two accounts for a specific message type. For example, if an admin (the granter) wants to give a user (the grantee) the right to submit claims for several collections, all of the constraints must go in a single authorisation.

Rules to remember

  1. A new grant overrides the old one. A new authorisation for the same message type between the same accounts overrides any existing authorisation, including its constraints.
  2. Query by message type. To query an authorisation you need the actual message type, for example /ixo.claims.v1beta1.MsgSubmitClaim, not the authorisation type.
  3. Revoke by message type. To revoke an authorisation you specify the correct message type URL, not the authorisation type.