Go back to the web Sign In

API Keys

Create scoped API keys for CI/CD pipelines and integrations.

Prerequisites

  • Role required: Owner or Admin
  • Location: Settings → API Keys

Create an API key

  1. Navigate to Settings → API Keys.
  2. Fill in the form on the left:
    • Name — A descriptive label (e.g., "GitHub Actions Production")
    • Environment — Optional tag for the CI/CD platform
    • Expiration — 30, 90, 180 days, 1 year, or no expiration
    • Scopes — Permissions for this key (see below)
  3. Click Create.
  4. Copy the key from the modal immediately.

Warning: This is the only time you'll see the complete key. Store it in your CI/CD platform's secrets manager. The key cannot be retrieved after closing the modal.

Scopes

Scopes control what the API key can do. Grant only the permissions needed.

Tip: If you leave scopes empty, the key has full access. Always select specific scopes for production keys.

Scope hierarchy

Write access includes read. Delete access includes write and read.

Available scopes

Scope Description
sbom:read View and download SBOMs, HBOMs, VEX documents
sbom:write Upload and modify artifacts
sbom:delete Remove artifacts
product:read List and view products
product:write Create and modify products
product:delete Remove products
version:read List and view versions
version:write Create and modify versions
version:delete Remove versions
document:read Download documents
document:write Upload compliance documents
document:delete Remove documents
vuln:read View vulnerability data
vuln:write Update status and add notes
export:read Generate technical file exports
firmware:read/write/delete Manage firmware files
hardware:read/write/delete Manage HBOM components

Common scope combinations

Use case Scopes
CI/CD SBOM upload sbom:write, version:write
Read-only dashboard sbom:read, product:read, vuln:read
Full automation sbom:write, version:write, document:write

Authenticate API requests

Include the API key in the Authorization header using the Bearer scheme:

curl -H "Authorization: Bearer cra_your_key_here" \
  https://api.craevidence.com/api/v1/products

CI/CD integration examples

GitHub Actions

  1. Add CRA_API_KEY to Settings → Secrets and variables → Actions.
  2. Reference it in your workflow:
name: Upload SBOM
on: [push]

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - name: Generate SBOM
        run: syft . -o cyclonedx-json > sbom.json

      - name: Upload to CRA Evidence
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.CRA_API_KEY }}" \
            -F "file=@sbom.json" \
            -F "version_id=$VERSION_ID" \
            https://api.craevidence.com/api/v1/sboms/ingest

GitLab CI

  1. Add CRA_API_KEY in Settings → CI/CD → Variables.
  2. Use it in .gitlab-ci.yml:
upload-sbom:
  stage: deploy
  script:
    - syft . -o cyclonedx-json > sbom.json
    - |
      curl -X POST \
        -H "Authorization: Bearer $CRA_API_KEY" \
        -F "file=@sbom.json" \
        -F "version_id=$VERSION_ID" \
        https://api.craevidence.com/api/v1/sboms/ingest

Jenkins

  1. Add credentials as Secret Text with ID cra-api-key.
  2. Reference in Jenkinsfile:
pipeline {
    stages {
        stage('Upload SBOM') {
            steps {
                withCredentials([string(credentialsId: 'cra-api-key', variable: 'CRA_API_KEY')]) {
                    sh '''
                        curl -X POST \
                            -H "Authorization: Bearer $CRA_API_KEY" \
                            -F "file=@sbom.json" \
                            -F "version_id=$VERSION_ID" \
                            https://api.craevidence.com/api/v1/sboms/ingest
                    '''
                }
            }
        }
    }
}

Manage existing keys

The API Keys page shows all active keys with:

Column Description
Name Your descriptive label
Key prefix First 12 characters for identification
Environment CI/CD platform tag
Last used When the key was last authenticated
Expires Expiration date or "Never"

Tip: Keys not used in months are candidates for revocation.

Revoke a key

  1. Navigate to Settings → API Keys.
  2. Click Revoke next to the key.
  3. Confirm the action.

Warning: Revocation takes effect within 30 seconds. Update your CI/CD secrets before revoking an active key.

Security best practices

Practice Why it matters
Use scopes Limits damage if key is compromised
Set expiration Forces regular rotation (90 days recommended)
Store in secret managers Never commit keys to version control
Name descriptively Easy identification during incidents
Audit regularly Revoke unused or unrecognised keys
Rotate immediately if exposed Don't wait to assess impact

Audit logging

All API key operations are recorded:

  • Key creation (by whom, with what scopes)
  • Authentication attempts (IP, timestamp)
  • Key revocation

Access the audit log in Settings → Audit Log.

Limitations

API keys cannot:

  • Create, list, or revoke other API keys
  • Access billing information
  • Change organisation settings

These operations require user authentication through the web interface.

CLI command scope requirements

When creating API keys for the CLI, use this table to select the minimum scopes needed:

CLI Command Minimum Scopes
upload-sbom sbom:write
upload-sbom --create-product --create-version sbom:write, product:write, version:write
upload-hbom sbom:write
upload-vex sbom:write
scan sbom:write
status sbom:read
release version:write
compare sbom:read
export export:read
distributor (read) product:read
distributor (write) product:write

For CI/CD pipelines that upload SBOMs and check compliance, the recommended scopes are: sbom:write, sbom:read, version:write.

Last updated February 27, 2026
Was this page helpful?
Thanks for your feedback!

Help us improve. What was missing or unclear?