Skip to main content

Manage your API keys

An API key is a secure way to interact with nullplatform programmatically, ideal for automation and system tasks. For machine users, like CI workflows, you can 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.

You need an ADMIN or OPS role to create and manage API keys.

You can create and manage API keys via UI, CLI, and API.

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

Create an API key​

  1. Go to Platform settings > API keys and click + New API key.
  2. Enter the configuration details: a descriptive name, grants, and optional tags.
  3. Click Generate API key.

Grants​

Grants define the access permissions for the API key (that is, where the key applies and what role it has).

  • Resource: The resource where permissions apply, e.g. account – main.
  • Role: The role assigned for that resource, e.g. Agent.

You can add multiple resource-and-role pairs.

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.

Using the CLI or API​

Create an API key​

Send a POST request to create your API keys.

Here's an example request:

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"
      }
    ]
  }'

where:

grants defines the access permissions for the API key.

  • nrn where the api keys's role is assigned.

  • role_slug 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.

    See Grant access to API keys below for more info.

Example response​

You'll receive a 2XX response like this:

{
  "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.

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 or update an API key:

  • nrn Specifies the resource where the API key's role will be assigned.
  • role_slug 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.
"grants": [
  {
    "nrn": "organization=1:account=2:namespace=3:application=4",
    "role_slug": "admin"  // Alternatively, use "role_id": "696188987"
  }
]

In this example, the role application:admin is assigned to the NRN organization=1:account=2:namespace=3:application=4. This allows the API key to handle tasks like creating, modifying, deleting the applications and its scopes for the resource.

For the complete list of available role IDs, see 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 article.

Send a POST request to get your token. You can use either:

  • your API key, or
  • your username and password

Here're are examples:

np token create
  --body '{
    "api_key": "AAAA.1234567890abcdef1234567890abcdefPTs="
  }'

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

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

Response

You'll receive a 2XX response like this:

{
  "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 to create a new one. You'll need your refresh_token and organization_id for the request.

Example request:

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

Example response:

{
  "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 with the details you want to change.

You'll need the API key id for this request.

To get the API key ID, send a GET request to list all the API keys.

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

np api-key patch \
  --id 123 \
  --body '{
    "name": "updated-machine-process",
    "tags": [
      {
        "key": "CI",
        "value": "updated"
      }
    ]
  }'

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:

{
  "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.

You'll need the API key id for this request.

To get the API key ID, send a GET request to list all the API keys.

Here's an example request:

np api-key delete \
  --id 123 \
  --auth "Bearer {{access_token}}"

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