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
Plane API Endpoint Supported Authentication Data Plane api.safedep.io
JWT and API Key Control Plane cloud.safedep.io
JWT
Data Plane Authentication
API Key Authentication
The most common method for tool integrations and automated access:
Generate API Key
Create an API key in your SafeDep Cloud tenant settings
Configure Environment
Set the API key in your environment:
export SAFEDEP_API_KEY = your-api-key-here
export SAFEDEP_TENANT_ID = your-tenant-domain
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 }}
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-domai n >
# or
vet cloud login --tenant < tenant-domai n >
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
Responses are generated using AI and may contain mistakes.