Grants and permissions

Grants are the core of how authorization works in nullplatform. A grant is what gives a user permission to act on a resource.

In short:

• A role is a bundle of actions.
• A grant attaches that role to a user at a specific resource (NRN).
• The grant is what turns a role into real access.

If you’re new to roles, start with Roles.

How grants work

A grant always has three parts:

• User – the person or machine user receiving access
• Role – the bundle of actions they can perform
• NRN – the resource where the role applies

Grants apply to the selected resource and its child resources. For example, a grant on an account applies to all namespaces and applications under that account.

Grants are additive

Users can have multiple grants across different resources and roles.

Manage grant permissions

You can manage grants in these ways:

• From the UI – Go to Namespace and open the Team Management dashboard. You can add or remove user grants there.
• Using the CLI or API – Use the authorization API endpoints for grants and roles.

Grant access to API keys (machine users)

See the API keys docs to learn how to create and manage API keys and their grants.

Grant access to human users

Create a single grant when you’re giving access to one resource. You can use either the CLI or cURL. Send a POST request like the example below.

CLI

np authz grants create \
--body '{
"nrn": "organization=1:account=1:namespace=1:application=4",
"user_id": 12345,
"role_slug": "developer"
}'

cURL

curl -L 'https://api.nullplatform.com/authz/grants' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
"nrn": "organization=1:account=1:namespace=1:application=4",
"user_id": 12345,
"role_slug": "developer"
}'

Where:

• user_id is the ID of the user receiving the grant.
• nrn is the resource where the role is assigned.
• role_slug is the slug of the role assigned to the user for the specified NRN. You can also provide the role_id instead of role_slug.

When to use bulk or replace

When managing grants in bulk through the API, you have a few options:

• Bulk create grants when you need to add multiple grants at once.
• Replace all grants when you want to reset access for a user in one request. This removes all existing grants and replaces them with the new list (or removes everything if you send an empty array).

Example request to bulk create grants. Send a POST request like the example below.

curl -L 'https://api.nullplatform.com/user/:id/grant' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>' \
-d '[
  {
  "nrn": "organization=1:account=2",
  "role_slug": "developer"
  },
  {
  "nrn": "organization=1:account=3",
  "role_slug": "ops"
}
]'

Who can grant roles

Granting a permission means assigning a role to a user on a specific NRN and its child resources. For example, you can be assigned the Admin role on an application, namespace, account, or the entire organization.

Users can grant permissions to other users according to the following rules:

• Users can only grant permissions at the same or lower NRN level where they have their own grant.
• The role being granted must be one that the granter is authorized to assign:

Granter	Roles that can be granted
Admin	Admin, Member, Ops, Developer, SecOps, Insights viewer
Ops	CI, Secrets Reader, Agent

Grant removal

• Only users with the Admin role can remove grants.
• You can only remove grants at or below the NRN level where you hold the Admin role.

Roles vs. approvals & policies

Having a role on a certain resource doesn’t always mean you can act immediately. Your organization may require approvals for some actions. See Approvals for more details.