Lightrun system API keys🔗

You can generate and manage private system API keys in the Lightrun Management Portal. These organization-level keys authenticate integrations, automation, public API clients, and Lightrun MCP clients. Administrators generate the keys in the Management Portal and copy them to the target service 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 key are displayed.
• Agent Pool keys use a dedicated mechanism to register agents and are managed independently for each Agent Pool. They are different from the system API keys described on this page. 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.
• Starting from version 1.90, you can restrict system API keys with the Dev scope to specific agent pools.

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

Restrict API keys by agent pool🔗

Starting from Lightrun version 1.90, you can control where a system API key with the Dev scope can perform actions. Lightrun authorizes a request only when both conditions are met:

• The API key includes the permission scope required by the API or MCP tool.
• The target agent pool is included in the key's Agent Pool Access configuration.

Choose one of the following options:

• All Agent Pools: Grants access to every current and future agent pool in the organization.
• Specific Agent Pools: Grants access only to the agent pools you select.

Restricting a key to specific pools is optional. Use it to limit an integration or automation to the environments and services it requires.

You can also select Ignore the quota limits for the selected agent pools. This is a key-level setting: actions performed with the key ignore quota limits in the pools that the key can access. It is separate from the per-request ignoreQuota option available to authorized OAuth users in supported MCP tools.

You can perform the following API key tasks:

• 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 Level options: Company, Dev, and Security. For more information, see Control API usage using scoped APIs.

8. If you selected Dev, configure Agent Pool Access:

   • Select All Agent Pools to allow access to all current and future pools.

   • Select Specific Agent Pools, click + Add, and select one or more pools. Use the search field to find pools, then click Add.

     

9. (Optional) Select Ignore the quota limits for the selected agent pools when the integration must perform actions without consuming the configured action quota.

10. Click Generate.

    Lightrun displays the generated key once. 11. Copy the key and store it securely, then close the panel.

    The key is added to the API keys list. The Agent Pools column displays All or the number of selected pools, and the Ignore Quota column identifies keys configured to bypass quota limits. Open a key's details to review its permission and agent-pool access settings.

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.

The command above omits the agent-pool parameters, so the permanent key retains the backward-compatible default of All Agent Pools. To create a restricted key through the API, provide agentPoolAccessType=SPECIFIC together with one or more agentPoolIds values. For the complete request contract, see Create system API key.

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.