SafeDep Cloud API operates on two distinct planes, each with different authentication requirements and access patterns.

API Architecture

Control Plane

Configuration, reporting, and management operations

Data Plane

Package insights, scanning data, and tool integrations

All APIs for security tools integration are part of the Data Plane. These APIs require an API key for authentication and may enforce rate limits under a fair usage policy.

API Endpoints and Authentication

PlaneAPI EndpointSupported Authentication
Data Planeapi.safedep.ioJWT and API Key
Control Planecloud.safedep.ioJWT

Data Plane Authentication

API Key Authentication

The most common method for tool integrations and automated access:

1

Generate API Key

Create an API key in your SafeDep Cloud tenant settings

2

Configure Environment

Set the API key in your environment:

export SAFEDEP_API_KEY=your-api-key-here
export SAFEDEP_TENANT_ID=your-tenant-domain
3

Use with vet

Configure vet to use the API key:

vet auth configure --tenant your-tenant-domain

JWT Authentication

For programmatic access requiring higher privileges:

# Authenticate and get JWT token
vet cloud login --tenant your-tenant-domain

# Verify authentication
vet cloud whoami

Control Plane Authentication

OAuth2/OIDC Integration

SafeDep Cloud Identity Service is hosted at https://auth.safedep.io and provides OAuth2/OIDC compatible authentication.

OpenID Configuration Endpoint:

https://auth.safedep.io/.well-known/openid-configuration

Device Code Flow

For command-line tools, use the OAuth2 Device Code flow:

# Initiate device code flow
vet cloud login --tenant your-tenant-domain

This opens a browser for authentication and stores the JWT token locally.

Programmatic Integration

For custom applications, implement OAuth2 Device Code flow. Reference implementation available in the vet OAuth2 client.

Authentication Examples

Basic API Key Usage

# Set credentials
export SAFEDEP_API_KEY=sk_your_api_key
export SAFEDEP_TENANT_ID=your-company

# Use with vet
vet scan -D . --report-sync \
  --report-sync-project myproject \
  --report-sync-project-version main

JWT-Based Access

# Login with device code flow
vet cloud login --tenant your-company

# Query aggregated data
vet cloud query execute --sql "SELECT * FROM projects"

# Check authentication status
vet cloud whoami

GitHub Actions Integration

- name: SafeDep Cloud Integration
  uses: safedep/vet-action@v1
  with:
    cloud: true
    cloud-key: ${{ secrets.SAFEDEP_CLOUD_API_KEY }}
    cloud-tenant: ${{ secrets.SAFEDEP_CLOUD_TENANT }}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Authentication Headers

API Key Authentication

curl -H "Authorization: Bearer sk_your_api_key" \
     -H "X-Tenant-ID: your-tenant" \
     https://api.safedep.io/v2/insights/packages

JWT Authentication

curl -H "Authorization: Bearer your_jwt_token" \
     -H "X-Tenant-ID: your-tenant" \
     https://cloud.safedep.io/api/v1/projects

Rate Limiting

Data Plane Limits

  • API Key Authentication: Fair usage policy applies
  • Rate limits: 1000 requests per hour per API key
  • Burst capacity: 50 requests per minute

Control Plane Limits

  • JWT Authentication: Higher limits for authenticated users
  • Rate limits: 5000 requests per hour per user
  • Burst capacity: 100 requests per minute

Security Best Practices

Troubleshooting Authentication Issues

Common Error Messages

”User Not Found”

ERRO[0001] Failed to execute whoami: rpc error: code = Unauthenticated desc = unauthenticated: Token auth failed: No user: record not found

Solution: The user is not registered. Follow the quickstart guide to register with SafeDep Cloud.

”Tenant Not Found”

ERRO[0001] Failed to execute query: rpc error: code = Unknown desc = failed to resolve tenant: record not found

Solution: Configure the tenant using:

vet auth configure --tenant <tenant-domain>
# or
vet cloud login --tenant <tenant-domain>

If you’ve forgotten your tenant domain:

vet cloud login
vet cloud whoami  # Shows available tenants

Authentication Debugging

# Check current authentication status
vet cloud whoami

# Verify API key configuration
vet auth verify

# Clear stored authentication
vet auth logout

# Re-authenticate
vet cloud login --tenant your-tenant

API Reference