Create a principal via POST /api/management/v1/principals with a name and optional client-id/secret
Create a principal role via POST /api/management/v1/principal-roles
Assign the principal role to the principal via PUT /api/management/v1/principals/{principalName}/principal-roles
Create a catalog role via POST /api/management/v1/catalogs/{catalogName}/catalog-roles
Grant the catalog role to the principal role via PUT /api/management/v1/principal-roles/{principalRoleName}/catalog-roles/{catalogName}
Assign specific privileges to the catalog role via POST /api/management/v1/catalogs/{catalogName}/catalog-roles/{catalogRoleName}/grants
Known gotchas
Polaris uses a two-tier role model: principal roles are assigned to principals, and catalog roles (which hold actual data privileges) are granted to principal roles — you cannot directly grant a catalog role to a principal
Privileges are scoped to a specific entity level (catalog, namespace, table); a privilege on a namespace does not automatically apply to the catalog level
Deleting a principal role does not automatically revoke its catalog role assignments; clean up grants explicitly to avoid orphaned access
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp