Lightrun system API keys🔗

You can generate and manage private system API keys in the Lightrun Management Portal. These keys are assigned per organization and are essential for configuring SCIM endpoints and Lightrun Prometheus integration. Administrators must generate the keys in the Lightrun Management Server and copy them to the target endpoint during the generation process.

API Key rules and limitations🔗

• Starting from version 1.47, the Lightrun API Key feature has been updated. API keys can only be copied during generation. To make it easier to distinguish between different API keys, we added an option to set labels. If you have not set a label, only the last three characters of the API are displayed.
• API Keys for Agents Pools use a dedicated mechanism and are managed independently for each Agent Pool. For more information, see Manage Agent Pools.
• API Keys expire automatically after the predefined period you set when initially generating the API Key and can also be deactivated at any time. Note that it is your responsibility to track the validity of the tokens to ensure secure and uninterrupted access.
• Starting from version 1.71, you can assign scoped APIs to manage API access.

Control API usage using scoped APIs🔗

Starting from version 1.71, you can use Scoped APIs—an extension of the persona-based roles feature—to precisely control API access. Scoped APIs align API permissions with the Lightrun preset roles, improving security, auditability, and compliance.

By assigning Scoped APIs to API keys, you can enforce the principle of least privilege, granting access only to the specific API groups needed for each user or automation script. This approach replaces broad, full-access permissions with targeted, role-aligned scopes.

Supported scope categories🔗

You can assign one or more of the following scope categories to an API key:

You have the flexibility to perform various tasks related to API Keys, including:

• Generate an API Key
• Generate an initial API Key
• Revoke and delete an API Key

Generate an API Key🔗

1. Log in to your Lightrun account.
2. Click Settings on the top right-hand of the taskbar to navigate to the Settings dashboard.

3. Select API Keys under Security in the Settings dashboard sidebar.

   

4. Click Generate an API Key.

   

5. In the Key label field, enter a descriptive label to help identify the key later. If no label is assigned, the last three characters of the key will remain visible after generation for security reasons.

6. (Optional) From the Expiration period list, you can leave the default 90 days or select an alternate range.

7. (Optional) Select one or more scopes from the API Permission Levels options — such as Company, Dev, and/or Security. Supported from version 1.70.3, you can further restrict API access by mapping specific roles to the corresponding API scopes. This ensures that users can perform only the API operations relevant to their responsibilities and area of work. For more information, see Control API usage using scoped APIs.

8. Click Generate.

   The API Key Generated Successfully dialog opens.

   

9. Click Close.

   The key is added to the API keys list.

Generate an initial system API key🔗

To automate the Lightrun deployment process, generate an initial system API key. This key is valid for 24 hours and is encrypted to protect sensitive information. After the key expires, generate a fixed system API key using the method described above.

To set the initial API key, add the following environment variable under the extraEnvs section of the Lightrun Helm Chart:

extraEnvs:
  - name: LIGHTRUN_INITIAL_SYS_API_KEY
    value: 'your_initial_api_key'

[Mandatory] Generate a permanent API key using the init key🔗

After generating the initial key, proceed to create a permanent system API key. The initial key is only used for this one-time step and cannot be used for any other functionality provided by permanent API keys. Run the following command:

curl -X POST https://<your-domain>.com/api/v1/access/company/$ORG/system-api-key?expirationDays=3
  -H "Authorization: Bearer $TOK"

Response:

200 OK
{
  "apiKey": "ae404584-723e-4ca4-941a-84de93d37a8e"
}

• Replace $TOK with the initial key value.
• Replace $ORG with your organization's identifier.

Use the returned apiKey as your permanent system API key for ongoing authentication.

Revoke and delete an API Key🔗

Revoking and deleting API Keys is crucial for system security. Immediately revoke an API key if it's compromised, misused, hits its usage limit, belongs to an inactive user, is obsolete, or needs regular renewal. Once revoked, the API key denies access to the related service.

1. In the row of the required key, click Revoke and Delete.

   The Revoke and Delete the API Key dialog opens.

   

2. Click Revoke and delete.

   The key is removed from the list.