Skip to main content

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.

You need an Admin or Ops role 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 and Grants and permissions.

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 to create an API key.

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 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:

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

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