---
sidebar_label: Grants and permissions
doc_id: 2b706b0b-3a8f-4b1c-9e8f-2e2e6d7a6a1b
description: >-
  How grants connect roles to users and resources, and how to manage grants in
  nullplatform.
keywords:
  - grants
  - permissions
  - roles
  - access control
  - authorization
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# 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](/docs/authorization/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.

:::tip 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](/docs/authorization/api-keys) 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](/docs/api/grants-create) like the example below. 

<Tabs
defaultValue="create-user-grant-cli"
values={[
{ label: 'CLI', value: 'create-user-grant-cli' },
{ label: 'cURL', value: 'create-user-grant-curl' },
]}>
  <TabItem value="create-user-grant-cli">

    ```bash
    np authz grants create \
    --body '{
    "nrn": "organization=1:account=1:namespace=1:application=4",
    "user_id": 12345,
    "role_slug": "developer"
    }'
    ```
  </TabItem>
  <TabItem value="create-user-grant-curl">

    ```bash
    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"
    }'
    ```
  </TabItem>
</Tabs>

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:

- **create grants in bulk** 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).

Send a [POST request](/docs/api/user-grants-bulk-create) like the example below.

```bash
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.  

:::warning 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](/docs/approvals/) for more details.
:::