Manage your API keys using the API

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.

API reference for this page

API keys endpoint: [ POST | LIST | GET | PATCH | PUT | DELETE ]
Token endpoint: [ POST ]

Create your API keys

Send a POST request to create your API keys.

Here's an example request:

CLI
cURL

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": "application:admin"  // Alternatively, use "role_id": "560594970"
      }
    ],
    "tags": [
      {
        "key": "CI",
        "value": "main"
      }
    ]
  }'

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": "application:admin"    // Alternatively, use "role_id": "560594970"
      }
    ],
    "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": "MTI4ODQwNDE1Mg==.WXRnSChAMkR7dHM4XXFAM3Y1Y1U5SnFhT3NmcAsxPTs=",  // Your new API key.
  "masked_api_key": "MTI4xxxxxPTs=",
  "tags": [
    {
      "key": "CI",
      "value": "main"
    }
  ],
  "grants": [
    {
      "nrn": "organization=1:account=2:namespace=3:application=4",
      "role_slug": "application:admin",
      "role_id": 560594970
    }
  ],
  "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 value will be 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, update, or replace 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": "application:admin"  // Alternatively, use "role_id": "560594970"
  }
]

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.

curl -L -X POST 'https://api.nullplatform.com/token' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "api_key": "MTI4ODQwNDE1Mg==.WXRnSChAMkR7dHM4XXFAM3Y1Y1U5SnFhT3NmcAsxPTs="
  }'

You'll receive a 2XX response like this:

{
  "refresh_token": "eyJjdHki...",   // A long-lived token used to obtain new access tokens.
  "access_token": "eyJraWQi...",    // A short-lived bearer token for making API calls.
  "organization_id": 134893727,     // The unique ID of the organization.
}

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:

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

Example response:

{
  "access_token": "eyJra1JQa...",    // Your renewed access_token for making API calls.
  "organization_id": 134893727, 
}

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:

CLI
cURL

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

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

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": "MTI4xxxxxPTs=",
  "tags": [
    {
      "key": "CI",
      "value": "updated"
    }
  ],
  "grants": [
    {
      "nrn": "organization=1:account=2:namespace=3:application=4",
      "role_id": 560594970,
      "role_slug": "application: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.

Replace your API key

To replace an existing API key, send a PUT request with the updated details 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:

CLI
cURL

np api-key update \
  --id 123 \
  --body '{
    "name": "updated-machine-process",
    "grants": [
      {
        "nrn": "organization=1:account=2:namespace=3:application=4",
        "role_slug": "application:admin"  // Alternatively, use "role_id": "560594970"
      }
    ],
    "tags": [
      {
        "key": "CI",
        "value": "updated"
      }
    ]
  }'

  curl -L -X PUT 'https://api.nullplatform.com/api_key/123' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
    "name": "updated-machine-process",
    "grants": [
      {
        "nrn": "organization=1:account=2:namespace=3:application=4",
        "role_slug": "application:admin"  // Alternatively, use "role_id": "560594970"
      }
    ],
    ],
    "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.
grants: The updated permissions for the API key.
nrn: The NRN where the role is assigned.
role_slug: The role slug for the API key. You can also use role_id, instead.
tags: The updated tags for the API key.

Example response:

{
  "id": "123",
  "name": "updated-machine-process",
  "masked_api_key": "MTI4xxxxxPTs=",
  "tags": [
    {
      "key": "CI",
      "value": "updated"
    }
  ],
  "grants": [
    {
      "nrn": "organization=1:account=2:namespace=3:application=4",
      "role_slug": "application:admin"  // Alternatively, use "role_id": "560594970"
    }
  ],
  "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:

id: The unique ID of the API key you want to update (e.g., 123).
name: The updated name for the API key.
grants: The updated permissions for the API key.
nrn: The NRN where the role is assigned.
role_id: The role ID for the API key.
role_slug: The role slug 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:

CLI
cURL

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

curl -L -X DELETE 'https://api.nullplatform.com/api_key/123'

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

API reference for this page​

Create your API keys​

Example response​

Grant access to API keys​

Generate an access token​

Renew an access token​

Update your API key​

Replace your API key​

Delete your API key​

API reference for this page

Create your API keys

Example response

Grant access to API keys

Generate an access token

Renew an access token

Update your API key

Replace your API key

Delete your API key