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

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.

• 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:

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

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

# 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:

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:

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

Error response (invalid token):

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

pylynk CLI Examples

Set the API key via environment variable (recommended):

export INTERLYNK_SECURITY_TOKEN="lynk_service_your_token_here"

Upload an SBOM:

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

Upload to a specific environment:

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

Download an enhanced SBOM:

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:

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

List products:

pylynk prods --output json

List vulnerabilities:

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.

# 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)