Skip to main content
The SafeDep Cloud API has two 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

Each plane has its own endpoint and authentication method:
  • Data plane (api.safedep.io): package insights, scanning, and malware analysis. Authenticated with an API key.
  • Control plane (cloud.safedep.io): tenant, policy, and management operations. Authenticated with a JWT.
For the full list of SafeDep hostnames, including the console, identity provider, community API, and hosted MCP server, see the Endpoints reference.

​
Data Plane Authentication

​
API Key Authentication

The standard 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  # e.g. your-team.your-org.safedep.io
3

Use with Vet

Configure Vet to use the API key:
vet auth configure --tenant your-tenant-domain

​
Control Plane Authentication

​
OAuth2/OIDC Integration

The SafeDep Cloud Identity Service at https://auth.safedep.io provides OAuth2/OIDC 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 the OAuth2 Device Code flow. A reference implementation is available in the Vet OAuth2 client.

​
Authentication Examples

​
Basic API Key Usage

# Set credentials
export SAFEDEP_API_KEY=your_api_key
export SAFEDEP_TENANT_ID=your-company.safedep.io

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

​
JWT-Based Access

# Login with the OAuth device code flow
safedep auth login --tenant your-company.safedep.io

# Query aggregated data
safedep query exec --sql "SELECT projects.name FROM projects WHERE projects.origin_source = 'SOURCE_GITHUB'"

# Check authentication status
safedep auth status

​
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_DOMAIN }}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

​
Authentication Headers

The SafeDep API is a gRPC API with a ConnectRPC facade, not a REST API. Regardless of transport (gRPC over HTTP/2 or JSON over HTTP/1.1), requests carry the same two headers:
HeaderValue
AuthorizationYour API key or JWT, sent as-is (no Bearer prefix)
X-Tenant-IDYour tenant domain (e.g. your-company.safedep.io)
  • Data plane (api.safedep.io) accepts an API key or a JWT.
  • Control plane (cloud.safedep.io) accepts a JWT.
For the available services and methods, see the canonical API specification at buf.build/safedep/api, which also publishes generated SDKs.

​
Rate Limiting

SafeDep Cloud enforces rate limits at the API gateway, measured per second, with no hourly quota:
  • Data plane (api.safedep.io): up to 500 requests/second per API key
  • Management API: up to 20 requests/second
These limits are subject to change.

​
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 your identity and accessible tenants

​
Authentication Debugging

# Check current authentication status
vet cloud whoami

# Verify API key configuration
vet auth verify

# Clear stored authentication
rm ~/.safedep/vet-auth.yml

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

​
API Reference

API Specification

Canonical gRPC/ConnectRPC schemas, docs, and generated SDKs

OAuth2 Implementation

Reference implementation for OAuth2 Device Code flow

Quick Start Guide

Get started with SafeDep Cloud authentication