Skip to main content
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

  • Store API keys securely using environment variables or secret management systems
  • Rotate API keys regularly (recommended: every 90 days)
  • Use different API keys for different environments (dev, staging, prod)
  • Never commit API keys to version control
  • JWT tokens have limited lifetime (typically 24 hours)
  • Implement automatic token refresh in long-running applications
  • Store tokens securely in the OS keychain when possible
  • Clear tokens on logout or application termination
  • Always use HTTPS for API communications
  • Implement proper certificate validation
  • Consider IP allowlisting for production environments
  • Monitor authentication logs for suspicious activity

​
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

Control Plane API

Management and configuration API documentation

Data Plane API

Insights and scanning data API documentation

OAuth2 Implementation

Reference implementation for OAuth2 Device Code flow

Quick Start Guide

Get started with SafeDep Cloud authentication
⌘I