# 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. Any user with this permission can create service tokens and select any role available in the organization. ### Token Scopes * **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 creator selects the role during creation — any role in the organization can be chosen regardless of the creator's own role. Choose the most restrictive role that satisfies the token's purpose. ### 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 **New 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. Click **Create**. 6. Copy the displayed token immediately. It will not be shown again. ### Creating a Service Token (UI) 1. Navigate to **Settings > Organization > Service Tokens**. 2. Click **New Service Token**. 3. Enter a **Token Name**. 4. Select a **Role** to assign to the token. This determines what the token can access. 5. Optionally set an **Expiration Date**. 6. Click **Create**. 7. 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 > Organization > Service 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. *** ## 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 | | Wrong API URL | `401` or connection errors | Verify `INTERLYNK_API_URL` is set to `https://api.interlynk.io/lynkapi` (or omit to use default) | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.interlynk.io/administration/api-key-management.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.