List Permission Groups

Beta

GET/v1/identity/permission-groups

This endpoint is idempotent. Learn more

Lists the permission catalog, organized into groups of related permissions.

Each group carries the individual permissions it covers; pair a permission's code with an action (create, read, update, or delete) to build the permission strings accepted when creating or updating a role. The catalog is platform-defined and identical for every account.

Permissions requiredValues:permissions:read

The role behind your API key or agent must grant every one of these permissions.

cursoroptional string

Opaque cursor token identifying where the page of results starts.

Use the cursor value embedded in a previous response's next_page_url or previous_page_url to fetch the adjacent page. Omit to start from the first page.

limitoptional integer

Maximum number of results to return in a single page.

qoptional string

Free-text search term used to filter results.

Which fields are matched against the term varies by endpoint.

include[]optional arrayenumValues:owner

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of permission_group

Resources in this page.

idstring

Permission group ID.

objectstringenumValues:permission_group

Resource type identifier.

codestring

Unique code identifying the permission group, such as customers.

namestring

Human-readable name for the permission group.

descriptionstringnullable

Free-form description of the permission group.

permissionslistnullable

The individual permissions collected under this group.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of permission

Resources in this page.

idstring

Permission ID.

objectstringenumValues:permission

Resource type identifier.

codestring

Stable code identifying the area this permission controls, such as customers or sales_orders.

Pair the code with an action (create, read, update, or delete) to form the permission strings used when creating or updating a role.

namestring

Human-readable name for the permission.

descriptionstringnullable

Human-readable description of what this permission controls.

groupstring

Code of the permission group this permission is listed under, such as inventory.

created_atstring (date-time)

When the permission was created.

updated_atstring (date-time)

When the permission was last updated.

ownerownerExpandablenullable

Provenance of this permission group.

Permission groups form the platform-defined permission catalog and are system-owned; they are the same across every account.

objectstringenumValues:owner

Resource type identifier.

typestringenumValues:systemaccount

Where this resource came from.

system: a platform-provided default shared across all accounts; not editable.
account: created and owned by a specific account; the account field identifies which.

accountaccountnullable

The account that owns this resource.

Present only when type is account; system-owned resources have no owning account.

Always returned as null in this endpoint.

created_atstring (date-time)

When the permission group was created.

updated_atstring (date-time)

When the permission group was last updated.

Responses

200

Successful response for List Permission Groups

List Permission Groups

import Augno from '@augno/sdk';

const client = new Augno({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const listPermissionGroup = await client.identity.retrievePermissionGroups();

console.log(listPermissionGroup.data);

import Augno from '@augno/sdk';

const client = new Augno({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const listPermissionGroup = await client.identity.retrievePermissionGroups();

console.log(listPermissionGroup.data);

200 example

{
  "object": "list",
  "page_info": {
    "next_page_url": "/v1/identity/permission-groups?cursor=eyJjIjoiMjAyNi0wNS0xMFQwMDowMDowMFoiLCJzIjoicGdfNTg0aGtpaGx5Mm1oIiwiZCI6ImYifQ.yjKnFXPH56z0LgDvSG1sSbe89LjCih8aYkXBs-N6KGE",
    "previous_page_url": null,
    "has_next_page": true,
    "has_prev_page": false
  },
  "data": [
    {
      "id": "pg_584hkihly2mh",
      "object": "permission_group",
      "code": "customers",
      "name": "Customers",
      "description": null,
      "permissions": {
        "object": "list",
        "page_info": {
          "next_page_url": null,
          "previous_page_url": null,
          "has_next_page": false,
          "has_prev_page": false
        },
        "data": [
          {
            "id": "perm_gum1nfdm75ro",
            "object": "permission",
            "code": "customers:read",
            "name": "Read Customers",
            "description": null,
            "group": "customers",
            "created_at": "2026-05-10T00:00:00Z",
            "updated_at": "2026-05-10T00:23:00Z"
          }
        ]
      },
      "owner": {
        "object": "owner",
        "type": "system",
        "account": null
      },
      "created_at": "2026-05-10T00:00:00Z",
      "updated_at": "2026-05-10T00:23:00Z"
    }
  ]
}

{
  "object": "list",
  "page_info": {
    "next_page_url": "/v1/identity/permission-groups?cursor=eyJjIjoiMjAyNi0wNS0xMFQwMDowMDowMFoiLCJzIjoicGdfNTg0aGtpaGx5Mm1oIiwiZCI6ImYifQ.yjKnFXPH56z0LgDvSG1sSbe89LjCih8aYkXBs-N6KGE",
    "previous_page_url": null,
    "has_next_page": true,
    "has_prev_page": false
  },
  "data": [
    {
      "id": "pg_584hkihly2mh",
      "object": "permission_group",
      "code": "customers",
      "name": "Customers",
      "description": null,
      "permissions": {
        "object": "list",
        "page_info": {
          "next_page_url": null,
          "previous_page_url": null,
          "has_next_page": false,
          "has_prev_page": false
        },
        "data": [
          {
            "id": "perm_gum1nfdm75ro",
            "object": "permission",
            "code": "customers:read",
            "name": "Read Customers",
            "description": null,
            "group": "customers",
            "created_at": "2026-05-10T00:00:00Z",
            "updated_at": "2026-05-10T00:23:00Z"
          }
        ]
      },
      "owner": {
        "object": "owner",
        "type": "system",
        "account": null
      },
      "created_at": "2026-05-10T00:00:00Z",
      "updated_at": "2026-05-10T00:23:00Z"
    }
  ]
}

List Permission Groups

Authorization

Query Parameters

Returns

Responses