---
sidebar_label: Manage your API keys
doc_id: bebadb09-1b5f-4f20-a2b4-b27254a9cbe5
description: >-
  Learn how to create and manage API keys for programmatic access with
  role-based permissions.
keywords:
  - API keys
  - authentication
  - access control
  - automation
  - permissions
---

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

# Manage your API keys

An API key lets you interact with nullplatform programmatically and is ideal for automation and system tasks.
For machine users like CI workflows, create API keys with specific roles to control access and permissions.

**Keep in mind:** API keys are sensitive, so handle them carefully to prevent unauthorized access.

:::info You need an [Admin or Ops role](/docs/authorization/roles) to create and manage API keys.
:::

You can create and manage API keys through the UI, CLI, or API.

## How API keys fit into authorization

API keys act as **machine users**, and each API key has one or more **grants**.

#### Grants

Grants define the API key's access: **where** it applies and **what role** it has.

- **Resource**: The resource where permissions apply, for example *account: main*.  
- **Role**: The role assigned for that resource, for example *Agent*.  

> ℹ️ **Note:** You can add multiple resource-and-role pairs.


For more details on grants and roles, see [Roles](/docs/authorization/roles) and [Grants and permissions](/docs/authorization/grants).



## Using the UI

Go to **Platform settings > API keys**. From this view, you can:

- View and manage active API keys in your organization  
- Create, edit, and delete API keys  
- Grant access to resources and assign roles  
- Add tags to help filter and locate your API keys  


## Using the CLI or API

### Create an API key

Send a [POST request](/docs/api/api-key-create) to create an API key.

Here's an example request:

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

    ```bash
    np api-key create \
    --body '{
        "name": "my-machine-process-that-will-access-nullplatform",
        "grants": [
          {
            "nrn": "organization=1:account=2:namespace=3:application=4",
            "role_slug": "admin"  // Alternatively, use "role_id". For example: "696188987"
          }
        ],
        "tags": [
          {
            "key": "CI",
            "value": "main"
          }
        ]
      }'
    ```
  </TabItem>
  <TabItem value="create-api-key-curl">

    ```bash
    curl -L -X POST 'https://api.nullplatform.com/api_key' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -d '{
        "name": "my-machine-process-that-will-access-nullplatform",
        "grants": [
          {
            "nrn": "organization=1:account=2:namespace=3:application=4",
            "role_slug": "admin"  // Alternatively, use "role_id". For example: "696188987"
          }
        ],
        "tags": [
          {
            "key": "CI",
            "value": "main"
          }
        ]
      }'
    ```
  </TabItem>
</Tabs>

Where:

- `grants` defines the access permissions for the API key.
- `nrn` is where the API key's role is assigned.
- `role_slug` is the slug of the role assigned to the API key for the specified NRN. You can also provide the `role_id` instead of `role_slug`.



#### Example response

You'll receive a `2XX` response like this:

```json
{
  "id": "123",
  "name": "my-machine-process-that-will-access-nullplatform",
  "api_key": "AAAA.1234567890abcdef1234567890abcdefPTs=",  // Your new API key.
  "masked_api_key": "AAAA.xxxxxxxxxxxxxxxxxxxxxPTs=",
  "tags": [
    {
      "key": "CI",
      "value": "main"
    }
  ],
  "grants": [
    {
      "nrn": "organization=1:account=2:namespace=3:application=4",
      "role_slug": "admin",
      "role_id": 696188987
    }
  ],
  "owner_id": 1595,
  "last_used_at": null,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

Where:

`api_key` is your newly created API key.

:::warning Save your API key securely.
The API key is **displayed only once**. Make sure to store it in a secure location, as it cannot be retrieved later.
:::

### Grant access to API keys

You can use the `grants` field to assign or update roles for your API keys, just like you do for users.

To grant access, include the following in your request to [create](/docs/api/api-key-create) or [update](/docs/api/api-key-update) an API key:
- `nrn` specifies the resource where the API key's role will be assigned.
- `role_slug` is the slug of the role you want to assign to the API key for the specified NRN. You can also provide the `role_id` instead of `role_slug`.

```json
"grants": [
  {
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "role_slug": "admin"  // Alternatively, use "role_id": "696188987"
  }
]
```
In this example, the `admin` role is assigned to the NRN `organization=1:account=2:namespace=3:application=4`. This allows the API key to handle tasks like creating, modifying, and deleting applications and their scopes for the resource.

:::info For the complete list of available role IDs, see [Roles](/docs/authorization/roles).
:::

### Generate an access token

Use your new API key to create an access token, which allows you to authenticate and make API calls with nullplatform.

:::note
  These instructions are for API keys and machine users. If you're a human user, check the [Authorization](/docs/authorization/) article.
:::

Send a [POST request](/docs/api/access-token-create) to get your token. You can use either:

- your API key, or
- your username and password

Here are examples:

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

```bash
curl -L -X POST 'https://api.nullplatform.com/token' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "api_key": "AAAA.1234567890abcdef1234567890abcdefPTs="
  }'
```

  </TabItem>
  <TabItem value="create-token-cli">

  ```bash  
  np token create \
    --body '{
      "api_key": "AAAA.1234567890abcdef1234567890abcdefPTs="
    }'
  ```
  </TabItem>
</Tabs>


Instead of an API key, you can send the username, password, and organization ID. Like this:

```json
{
  "username": "alex.doe@email.com",
  "password": "your_password",
  "organization_id": "1234"
}
```

**Response**

You'll receive a `2XX` response like this:

```json
{
  "refresh_token": "epJjdHky...",   // A long-lived token used to obtain new access tokens.
  "access_token": "epJraWQy...",    // A short-lived bearer token for making API calls.
  "organization_id": 123245,     // The unique ID of the organization.
  "token_expires_at": 1700000000000
}
```

### Renew an access token

When your access token expires, you can make a [POST request](/docs/api/access-token-create) to create a new one. You'll need your `refresh_token` and `organization_id` for the request.

Example request:

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

  ```bash  
  np token create \
    --body '{
      "refresh_token": "epJjdHky...",
      "organization_id": "123245"
    }'
  ```    

  </TabItem>
  <TabItem value="renew-token-curl">

  ```bash
  curl -L -X POST 'https://api.nullplatform.com/token' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
      "refresh_token": "epJjdHky...",
      "organization_id": "123245"
  }'
  ```

  </TabItem>
</Tabs>

Example response:

```json
{
  "access_token": "eyJra3JQb...",    // Your renewed access_token for making API calls.
  "organization_id": 123245
}
```

### Update your API key

To update an existing API key, send a [PATCH request](/docs/api/api-key-update) with the details you want to change.

:::note You'll need the API key `id` for this request. 
To get the API key ID, send a [GET request](/docs/api/api-key-list) to list all the API keys.
:::


Here's an example request to update the API key name and tags:

<Tabs
defaultValue="patch-api-key-cli"
values={[
{ label: 'CLI', value: 'patch-api-key-cli' },
{ label: 'cURL', value: 'patch-api-key-curl' },
]}>
  <TabItem value="patch-api-key-cli">

    ```bash
    np api-key patch \
      --id 123 \
      --body '{
        "name": "updated-machine-process",
        "tags": [
          {
            "key": "CI",
            "value": "updated"
          }
        ]
      }'
    ```
  </TabItem>
  <TabItem value="patch-api-key-curl">

    ```bash
      curl -L -X PATCH 'https://api.nullplatform.com/api_key/123' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -d '{
        "name": "updated-machine-process",
        "tags": [
          {
            "key": "CI",
            "value": "updated"
          }
        ]
      }'
    ```
  </TabItem>
</Tabs>

Where:

- `id`: The unique ID of the API key you want to update (e.g., `123`).
- `name`: The **updated** name for the API key.
- `tags`: The **updated** tags for the API key.

Example response:

```json
{
  "id": "123",
  "name": "updated-machine-process",
  "masked_api_key": "AAAA.xxxxxxxxxxxxxxxxxxxxxPTs=",
  "tags": [
    {
      "key": "CI",
      "value": "updated"
    }
  ],
  "grants": [
    {
      "nrn": "organization=1:account=2:namespace=3:application=4",
      "role_id": 696188987,
      "role_slug": "admin"
    }
  ],
  "owner_id": 1595,
  "last_used_at": "2025-01-10T00:00:00Z",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2025-01-10T00:00:00Z"
}
```
Where:

- `name`: The **updated** name for the API key.
- `tags`: The **updated** tags for the API key.
- `updated_at`: The time when the API key was last updated.


### Delete your API key

To permanently remove an API key, send a [DELETE request](/docs/api/api-key-delete).

:::note You'll need the API key `id` for this request. 
To get the API key ID, send a [GET request](/docs/api/api-key-list) to list all the API keys.
:::

Here's an example request:

<Tabs
defaultValue="delete-api-key-cli"
values={[
{ label: 'CLI', value: 'delete-api-key-cli' },
{ label: 'cURL', value: 'delete-api-key-curl' },
]}>
<TabItem value="delete-api-key-cli">

    ```bash
    np api-key delete \
      --id 123 \
      --auth "Bearer {{access_token}}"
    ```
  </TabItem>
  <TabItem value="delete-api-key-curl">

  ```bash
  curl -L -X DELETE 'https://api.nullplatform.com/api_key/:id' \
  -H 'Authorization: Bearer <token>'
  ```
  </TabItem>
</Tabs>

You'll receive a `204` response, confirming your API key has been removed successfully.