> For the complete documentation index, see [llms.txt](https://docs.interlynk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interlynk.io/administration/api-key-management.md).

# API Key Management

API keys authenticate programmatic access to the Interlynk platform — from CI/CD pipelines, the `pylynk` CLI, and direct API calls. Interlynk supports two token types: **user tokens** (tied to an individual) and **service tokens** (tied to an organization).

***

## Token Types

| Property         | User Token                                      | Service Token                                                               |
| ---------------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
| Bound to         | Individual user account                         | Organization                                                                |
| Permissions      | Inherits user's role                            | Assigned a specific role at creation                                        |
| Creator tracking | N/A                                             | Records who created it (`creator_id`)                                       |
| Lifecycle        | Tied to user — invalidated when user is removed | Outlives the creator — persists even if the creator leaves the organization |
| Visibility       | Visible only to the owning user                 | Admins see all; non-admins see only tokens they created                     |
| Use case         | Personal CLI/API access                         | CI/CD pipelines, automation                                                 |
| Prefix           | `lynk_live_*`                                   | `lynk_service_*`                                                            |
| Limit            | No hard limit                                   | 100 per organization                                                        |

***

## Token Creation

### When to Create Tokens

* **User tokens**: For individual developers or security engineers interacting with the API or CLI during local development.
* **Service tokens**: For CI/CD pipelines, automated SBOM uploads, scheduled jobs, or any non-interactive access.

### Required Permissions

* Creating **user tokens** requires the `manage_api_tokens` permission.
* Creating **service tokens** requires the `manage_api_tokens` permission. Admins can assign any role. Other users can assign only roles that grant no permission they lack themselves, and never the Admin role.

### Token Scopes

A token's role decides what it can do. Its product scope decides which products it can see.

* **User tokens** inherit the full permission set of the user's current organization role.
* **Service tokens** are assigned a specific organization role at creation time. The role list shows only the roles you are allowed to assign, and the server rejects any other. Choose the most restrictive role that satisfies the token's purpose.

### Product Scope

By default a token can see every product in the organization. Both user tokens and service tokens can instead be limited to chosen products. Use this for AI agents and MCP clients such as [lynk-mcp](https://github.com/interlynk-io/lynk-mcp), and for pipelines that build a single product, so each one reaches only the products it works on.

A product-scoped token sees:

* The products it was granted, with their Environments, Versions and SBOMs.
* The products of any parts those SBOMs include, repeated through nested parts. A part's product, and that product's other SBOMs, come into scope this way.
* Product-owned data such as components, vulnerabilities, VEX, patches and annotations, only for the products above.
* Organization-level data such as roles, labels, policies, connections and settings.

A product outside the scope behaves as if it does not exist: requests for it return the same response as a nonexistent ID.

{% hint style="warning" %}
Product scope does not filter everything yet:

* Organization-wide aggregates (organization SBOM metrics, organization-wide vulnerability and component lists, policy results) still report numbers across all products. The trend metrics under [Metrics](https://docs.interlynk.io/product-guides/insights/analytics.md#metrics-alpha), such as Open Backlog and SLA breaches, are scoped: a scoped token reads them only for its products, and an SBOM in a product outside the scope reads as not collected.
* SBOM requests and share links are organization-level, so a scoped token can read and manage them for any product.

Do not rely on product scope alone to keep these out of reach of a token.
{% endhint %}

API tokens cannot create or delete products, whatever their scope or role. Those actions require a signed-in user.

**Changing the scope.** A user who manages the token can replace its product list or clear it from the token's edit dialog. Clearing the list returns the token to access across all products, so treat it as the highest-impact edit you can make to a token. If every product in a token's scope is deleted, the token sees nothing until you choose new products or clear the scope.

The **Scope** column in the token list shows **All products** for an unscoped token, or the number of products with their names on hover.

### Expiration Best Practices

| Environment           | Recommended Expiration |
| --------------------- | ---------------------- |
| Development           | 30 days                |
| CI/CD pipelines       | 90 days                |
| Production automation | 90–180 days            |
| Temporary/one-off     | 24 hours or 7 days     |

Tokens without an expiration date remain valid until explicitly revoked. Avoid creating non-expiring tokens for CI/CD use.

### Security Considerations

{% hint style="warning" %}
The raw token value is displayed only once at creation time. It cannot be retrieved afterward. Copy it immediately and store it in a secrets manager.
{% endhint %}

* Tokens are stored as HMAC-SHA256 digests. Interlynk cannot recover a lost token.
* All token usage is tracked with a `last_used_at` timestamp.
* Revoked or expired tokens are rejected immediately on any API call.

### Creating a User Token (UI)

1. Navigate to **Settings > Personal > Security tokens**.
2. Click the **+** button and choose **Personal Token**.
3. Enter a descriptive **Token Name** (4–128 characters). Use a name that identifies the purpose, such as `ci-sbom-upload` or `local-dev`.
4. Optionally set an **Expiration Date**. Uncheck "No Expiration" to enable the date picker.
5. Optionally choose **Products** to limit the token to. Leave it empty to give the token access to all products. See [Product Scope](#product-scope).
6. Click **Create**.
7. Copy the displayed token immediately. It will not be shown again.

### Creating a Service Token (UI)

1. Navigate to **Settings > Personal > Security tokens**.
2. Click the **+** button and choose **Service Token**.
3. Enter a **Token Name**.
4. Select a **Role** to assign to the token. This determines what the token can do. The list shows only roles you are allowed to assign.
5. Optionally set an **Expiration Date**.
6. Optionally choose **Products** to limit the token to. Leave it empty to give the token access to all products.
7. Click **Create**.
8. Copy the displayed token immediately.

***

## Token Deletion

### Revoking Tokens

Revoking a token invalidates it immediately. Any API call or CLI command using a revoked token will receive a `401 Unauthorized` response.

**To revoke a user token:**

1. Navigate to **Settings > Personal > Security tokens**.
2. Click the action menu on the token row.
3. Select **Revoke**.

**To delete a service token:**

1. Navigate to **Settings > Personal > Security tokens**.
2. Click the action menu on the token row.
3. Select **Delete**.

### Impact Analysis

Before revoking a token, consider:

| Impact          | Details                                                                          |
| --------------- | -------------------------------------------------------------------------------- |
| CI/CD pipelines | Any pipeline using the token will fail on the next run                           |
| Scheduled jobs  | Automated SBOM uploads or downloads will stop                                    |
| Integrations    | Any webhook or external system authenticating with the token will lose access    |
| Other users     | Service tokens may be shared across teams — verify no other systems depend on it |

Check the token's `last_used_at` timestamp to determine if it is actively in use before revoking.

***

## Service Tokens

### User Token vs. Service Token

Use **service tokens** for any non-interactive, system-to-system access. Service tokens are bound to the organization, not the individual — they **outlive the creator**. If the team member who created a service token leaves the organization, the token continues to function with its assigned role.

Each service token tracks who created it. This enables:

* **Admins**: Full visibility — admins see all service tokens in the organization regardless of who created them, and can revoke or delete any token.
* **Non-admins**: Scoped visibility — non-admin users see only the service tokens they personally created, and can only manage their own.

Use **user tokens** only for personal, interactive use (local CLI sessions, ad hoc API calls).

### CI/CD Usage

Service tokens are the recommended authentication method for CI/CD pipelines:

```yaml
# GitHub Actions example
env:
  INTERLYNK_SECURITY_TOKEN: ${{ secrets.INTERLYNK_SERVICE_TOKEN }}

steps:
  - name: Upload SBOM
    run: pylynk upload --prod "my-app" --sbom sbom.json
```

```yaml
# GitLab CI example
variables:
  INTERLYNK_SECURITY_TOKEN: $INTERLYNK_SERVICE_TOKEN

upload_sbom:
  script:
    - pylynk upload --prod "my-app" --sbom sbom.json
```

### Least Privilege Recommendations

| Use Case                                             | Recommended Role                                           |
| ---------------------------------------------------- | ---------------------------------------------------------- |
| SBOM upload only                                     | Viewer (with upload permission) or custom upload-only role |
| SBOM upload + vulnerability review                   | Operator                                                   |
| Full automation (policy management, user management) | Admin (use sparingly)                                      |
| Read-only dashboards / reporting                     | Viewer                                                     |

Create a custom role with only the permissions required by the automation. Assign that role to the service token.

When a pipeline builds a single product, also limit its token to that product. The role narrows what the token can do, and the product scope narrows where it can do it.

***

## Token Usage

### curl Example

Upload an SBOM using the Interlynk GraphQL API:

```bash
curl -X POST https://api.interlynk.io/lynkapi \
  -H "Authorization: Bearer $INTERLYNK_SECURITY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { organization { projectGroups(first: 10) { totalCount nodes { id name } } } }"
  }'
```

**Successful response:**

```json
{
  "data": {
    "organization": {
      "projectGroups": {
        "totalCount": 3,
        "nodes": [
          { "id": "abc-123", "name": "my-app" }
        ]
      }
    }
  }
}
```

**Error response (invalid token):**

```json
{
  "errors": [
    { "message": "Authentication failed. Please check your token." }
  ]
}
```

### pylynk CLI Examples

**Set the API key via environment variable (recommended):**

```bash
export INTERLYNK_SECURITY_TOKEN="lynk_service_your_token_here"
```

**Upload an SBOM:**

```bash
pylynk upload --prod "my-app" --sbom ./sbom.cdx.json
```

**Upload to a specific environment:**

```bash
pylynk upload --prod "my-app" --env "production" --sbom ./sbom.cdx.json
```

**Download an enhanced SBOM:**

```bash
pylynk download --prod "my-app" --env "production" --ver "v1.2.0" \
  --out-file enhanced-sbom.json \
  --vuln true \
  --include-support-status true
```

**Download by version ID:**

```bash
pylynk download --verId "abc-123-def" --out-file sbom.json
```

**List products:**

```bash
pylynk prods --output json
```

**List vulnerabilities:**

```bash
pylynk vulns --prod "my-app" --vuln-details --vex-details --output json
```

***

## Best Practices

### Never Hardcode Tokens

Store tokens in a secrets manager or CI/CD secret store. Never commit tokens to source control.

```bash
# Correct — use environment variable
export INTERLYNK_SECURITY_TOKEN="$VAULT_SECRET"

# Incorrect — hardcoded in script
pylynk upload --token "lynk_service_abc123" --prod "my-app" --sbom sbom.json
```

### Rotation Strategy

1. Create a new token with the same role and permissions.
2. Update all systems (CI/CD pipelines, scripts, secrets managers) to use the new token.
3. Verify the new token is functioning by checking `last_used_at`.
4. Revoke the old token.

Rotate tokens on a regular schedule (every 90 days for production service tokens) and immediately if a token may have been exposed.

### Incident Response — Token Leak

If a token is leaked (committed to a public repo, logged in plaintext, exposed in a support ticket):

1. **Revoke immediately.** Navigate to the token management page and revoke or delete the token.
2. **Audit usage.** Check the token's `last_used_at` to determine if it was used after the leak.
3. **Create a replacement.** Issue a new token with the same role.
4. **Review scope.** If the leaked token had admin permissions, audit recent changes to the organization for unauthorized modifications.
5. **Rotate related secrets.** If the token was stored alongside other secrets, rotate those as well.

***

## Common Misconfigurations

| Issue                                            | Symptom                                                                          | Fix                                                                                                       |
| ------------------------------------------------ | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Token passed via `--token` flag in CI logs       | Token visible in build logs                                                      | Use `INTERLYNK_SECURITY_TOKEN` env var instead                                                            |
| Service token with Admin role                    | Excessive permissions for automation                                             | Create a custom role with minimum required permissions                                                    |
| No expiration set on service tokens              | Tokens remain valid indefinitely                                                 | Set 90-day expiration and rotate proactively                                                              |
| Token created by a user who left                 | Token still works but the creator is no longer in the org                        | Admins retain full visibility and can revoke orphaned service tokens; audit during offboarding            |
| Non-admin cannot find a service token            | Non-admins only see tokens they created                                          | Ask an admin to locate and manage the token, or re-create it under your own account                       |
| Scoped token cannot find a product               | Product lookups return not found                                                 | The product is outside the token's scope. Edit the token and add the product, or use a token scoped to it |
| Scoped token sees no products                    | Every product in the token's scope was deleted; the Scope column shows a warning | Edit the token to choose new products, or clear the scope                                                 |
| Non-admin cannot pick a role for a service token | Role missing from the list                                                       | Only roles within your own permissions are listed. Ask an admin to create the token                       |
| Wrong API URL                                    | `401` or connection errors                                                       | Verify `INTERLYNK_API_URL` is set to `https://api.interlynk.io/lynkapi` (or omit to use default)          |
