APG PayAPG Paydocs

Identity

Create roles

POST/roles

Define a role, carrying its own grants or grouping other roles. Selected by the body's type.

2 actionsRoleCmdCreateRoleCmdCreateGrouping

Permissions

Required permission
roles:create

Requires the `create` action on `roles` for the supplied runtime context

Request body

This body is a typed union. Pick a variant to see its fields and a matching example.

Discriminated by type
type = "RoleCmdCreate"
namestringrequired

Example Ada Lovelace

The domain that owns this role. Carries the party it is restricted to.

curl -X POST https://api.tst.au.apgpay.dev/roles \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "RoleCmdCreate",
  "name": "Ada Lovelace",
  "ownerDomain": {
    "type": "UserDomainAnonymous",
    "restrictedTo": {
      "type": "UserDomainCustomer",
      "customerId": "cust_9f2Kd8QpLzXw"
    }
  },
  "grants": [
    {
      "type": "RoleGrantAttributes",
      "resource": "BlockedCard",
      "actions": [
        "Create"
      ]
    }
  ]
}'

Responses

The response is a tagged shape: type is always "RoleCreateRspAttributes". Switch on it; subtypes can be added, and a client that already reads it will not break.

Discriminated by type
type = "RoleCreateRspAttributes"

The resource that was created.

Example
{
  "type": "RoleCreateRspAttributes",
  "created": {
    "type": "RoleViewBuiltIn",
    "roleId": "role_9f2Kd8QpLzXw",
    "name": "Ada Lovelace",
    "grants": [
      {
        "type": "RoleGrantAttributes",
        "resource": "BlockedCard",
        "actions": [
          "Create"
        ]
      }
    ],
    "createdAt": "2026-08-19T04:21:07Z",
    "updatedAt": "2026-08-19T04:21:07Z"
  }
}

Error responses