Using Guide Personal Access Tokens with OSS Index API Integrations

As part of the OSS Index migration to Sonatype Guide, you can now use your Guide Personal Access Token (PAT) to authenticate with the OSS Index API endpoints. This allows you to transition away from legacy OSS Index credentials while maintaining full compatibility with existing tools and integrations.

Overview

The OSS Index API endpoints accept authentication via HTTP Basic Auth:

Authorization: Basic <base64(username:token)>

Both legacy OSS Index tokens and Guide PATs work with this scheme. You do not need to change how your tools send credentials — only the token value itself changes.

Credential type	Username field	Token field
Guide PAT (new)	Any value (e.g. your email)	Your Guide Personal Access Token
OSS Index token (legacy)	Your OSS Index email	Your OSS Index API token

Creating a Guide Personal Access Token

Sign in to guide.sonatype.com
Open Settings from the user menu
Navigate to Personal Access Tokens
Click Generate New Token, give it a descriptive name (e.g. "CI/CD Pipeline" or "Dependency-Check"), and click Create
Copy the token immediately — it will not be shown again

Updating Your Integrations

Dependency-Check

Replace your OSS Index credentials with your Guide PAT. The username field can be any value (it is ignored for PAT authentication), but using your email keeps configurations consistent.

Maven plugin (pom.xml)

<configuration>
  <ossIndexAnalyzerUrl>https://api.guide.sonatype.com</ossIndexAnalyzerUrl>
  <ossIndexAnalyzerUsername>your-email@example.com</ossIndexAnalyzerUsername>
  <ossIndexAnalyzerPassword>YOUR_GUIDE_PAT</ossIndexAnalyzerPassword>
</configuration>

Gradle plugin (build.gradle)

dependencyCheck {
  analyzers {
    ossIndex {
      url = "https://api.guide.sonatype.com"
      username = "your-email@example.com"
      password = "YOUR_GUIDE_PAT"
    }
  }
}

CLI

dependency-check \
  --ossIndexUrl "https://api.guide.sonatype.com" \
  --ossIndexUser "your-email@example.com" \
  --ossIndexPassword "YOUR_GUIDE_PAT"

Dependency-Track

Go to Administration → Analyzers → OSS Index
Set Base URL to https://api.guide.sonatype.com/
Set Username to your email (or any value)
Set API Token to your Guide Personal Access Token
Click Save

Direct API Calls (curl)

Replace the token in your Basic Auth header:

# Single component lookup
curl -u "your-email@example.com:YOUR_GUIDE_PAT" \
  "https://api.guide.sonatype.com/api/v3/component-report/pkg:maven/org.example/library@1.0.0"

# Batch component lookup
curl -u "your-email@example.com:YOUR_GUIDE_PAT" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"coordinates":["pkg:maven/org.example/library@1.0.0","pkg:npm/lodash@4.17.21"]}' \
  "https://api.guide.sonatype.com/api/v3/component-report"

CI/CD Pipelines

Store your Guide PAT as a secret/environment variable in your CI system (e.g. GUIDE_PAT), then reference it in your build configuration:

GitHub Actions example:

- name: Run Dependency-Check
  env:
    OSSINDEX_USER: ${{ secrets.GUIDE_EMAIL }}
    OSSINDEX_TOKEN: ${{ secrets.GUIDE_PAT }}
  run: |
    dependency-check \
      --ossIndexUrl "https://api.guide.sonatype.com" \
      --ossIndexUser "$OSSINDEX_USER" \
      --ossIndexPassword "$OSSINDEX_TOKEN" \
      --scan .

Frequently Asked Questions

Do I need to change my integration URL and token at the same time?

No. You can update them independently. Guide PATs work on both the legacy https://ossindex.sonatype.org endpoint (until it is sunset) and the new https://api.guide.sonatype.com endpoint.

What happens if I use an invalid PAT?

If the PAT is invalid but you still have a valid legacy OSS Index token configured, authentication falls through to the legacy token. If both are invalid, you receive a 401 Unauthorized response.

Does the username matter when using a Guide PAT?

No. The username field is ignored for PAT authentication. You can use your email, an empty string, or any placeholder. We recommend using your email for consistency.

Will my existing OSS Index token stop working?

Legacy OSS Index tokens will continue to work until the sunset date (December 31, 2026). We recommend migrating to Guide PATs before then.