> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safedep.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Understand SafeDep Cloud authentication methods and API access patterns

The SafeDep Cloud API has two planes, each with different authentication requirements and access patterns.

## API Architecture

<CardGroup cols={2}>
  <Card title="Control Plane" icon="cog">
    Configuration, reporting, and management operations
  </Card>

  <Card title="Data Plane" icon="database">
    Package insights, scanning data, and tool integrations
  </Card>
</CardGroup>

<Info>
  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.
</Info>

## 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](/reference/endpoints).

## Data Plane Authentication

### API Key Authentication

The standard method for tool integrations and automated access:

<Steps>
  <Step title="Generate API Key">
    Create an API key in your SafeDep Cloud tenant settings
  </Step>

  <Step title="Configure Environment">
    Set the API key in your environment:

    ```bash theme={null}
    export SAFEDEP_API_KEY=your-api-key-here
    export SAFEDEP_TENANT_ID=your-tenant-domain  # e.g. your-team.your-org.safedep.io
    ```
  </Step>

  <Step title="Use with Vet">
    Configure Vet to use the API key:

    ```bash theme={null}
    vet auth configure --tenant your-tenant-domain
    ```
  </Step>
</Steps>

## 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:

```bash theme={null}
# 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](https://github.com/safedep/vet/blob/main/cmd/cloud/login.go).

## Authentication Examples

### Basic API Key Usage

```bash theme={null}
# 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

```bash theme={null}
# 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

```yaml theme={null}
- 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](/reference/api-introduction), not a REST API. Regardless of transport (gRPC over HTTP/2 or JSON over HTTP/1.1), requests carry the same two headers:

| Header          | Value                                                    |
| --------------- | -------------------------------------------------------- |
| `Authorization` | Your API key or JWT, sent **as-is** (no `Bearer` prefix) |
| `X-Tenant-ID`   | Your 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](https://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

<AccordionGroup>
  <Accordion title="API Key Management">
    * 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
  </Accordion>

  <Accordion title="JWT Token Handling">
    * 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
  </Accordion>

  <Accordion title="Network Security">
    * Always use HTTPS for API communications
    * Implement proper certificate validation
    * Consider IP allowlisting for production environments
    * Monitor authentication logs for suspicious activity
  </Accordion>
</AccordionGroup>

## 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](/governance/cloud/quickstart) 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:

```bash theme={null}
vet auth configure --tenant <tenant-domain>
# or
vet cloud login --tenant <tenant-domain>
```

If you've forgotten your tenant domain:

```bash theme={null}
vet cloud login
vet cloud whoami  # Shows your identity and accessible tenants
```

### Authentication Debugging

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="API Specification" icon="book" href="https://buf.build/safedep/api">
    Canonical gRPC/ConnectRPC schemas, docs, and generated SDKs
  </Card>

  <Card title="OAuth2 Implementation" icon="code" href="https://github.com/safedep/vet/blob/main/cmd/cloud/login.go">
    Reference implementation for OAuth2 Device Code flow
  </Card>

  <Card title="Quick Start Guide" icon="rocket" href="/governance/cloud/quickstart">
    Get started with SafeDep Cloud authentication
  </Card>
</CardGroup>