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

# Authentication

> API authentication methods, token types, and security best practices for the Shinzo Platform API.

# Authentication

The Shinzo Platform API uses multiple authentication methods depending on the type of operation. This guide covers all authentication types, their use cases, and security best practices.

## Authentication Methods

### 1. JWT Tokens (User Authentication)

**Purpose**: Authenticating users for dashboard and management API access.

JWT tokens are issued when users log in via email/password or OAuth. They provide access to user-specific resources and management endpoints.

```bash theme={null}
# Login to get a JWT token
curl -X POST https://api.app.shinzo.ai/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your_password"}'
```

Response:

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "uuid": "usr_abc123",
    "email": "user@example.com"
  }
}
```

**Token expiration**: 24 hours

**Header format**:

```bash theme={null}
Authorization: Bearer <jwt_token>
```

### 2. Ingest Tokens (Telemetry)

**Purpose**: Sending telemetry data from your MCP servers via the SDKs.

Ingest tokens are designed for use with the Shinzo SDKs and telemetry ingestion endpoints. They have write-only permissions for telemetry data.

```typescript theme={null}
// TypeScript SDK usage
const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_INGEST_TOKEN
  }
})
```

**Header format**:

```bash theme={null}
Authorization: <ingest_token>
```

### 3. Platform API Keys (Programmatic Access)

**Purpose**: Programmatic access to agent management, Spotlight analytics, and model proxy endpoints.

Platform API keys are designed for server-to-server communication, CI/CD pipelines, and automated workflows. They support authentication via multiple header formats.

```bash theme={null}
# Using x-shinzo-api-key header
curl -X GET https://api.app.shinzo.ai/agent/list \
  -H "x-shinzo-api-key: sk_shinzo_abc123..."

# Or using Authorization header
curl -X GET https://api.app.shinzo.ai/agent/list \
  -H "Authorization: Bearer sk_shinzo_abc123..."

# Or using x-api-key header
curl -X GET https://api.app.shinzo.ai/agent/list \
  -H "x-api-key: sk_shinzo_abc123..."
```

**Key format**: `sk_shinzo_*`

## Token Formats

| Token Type       | Format             | Example                     |
| ---------------- | ------------------ | --------------------------- |
| JWT Token        | Base64-encoded JWT | `eyJhbGciOiJIUzI1NiIs...`   |
| Ingest Token     | UUID               | `abc123-def456-...`         |
| Platform API Key | `sk_shinzo_*`      | `sk_shinzo_abc123def456...` |

## Generating Tokens

### JWT Tokens

JWT tokens are obtained by logging in:

* **Email/Password**: `POST /auth/login`
* **Google OAuth**: `GET /auth/oauth/google` then `POST /auth/oauth/google/callback`
* **GitHub OAuth**: `GET /auth/oauth/github` then `POST /auth/oauth/github/callback`

### Ingest Tokens

Generate ingest tokens via API (requires JWT authentication):

```bash theme={null}
curl -X POST https://api.app.shinzo.ai/auth/generate_ingest_token \
  -H "Authorization: Bearer <jwt_token>"
```

Or from your [Shinzo Platform dashboard](https://app.shinzo.ai) under **Settings > Tokens**.

### Platform API Keys

Create platform API keys via API (requires JWT authentication):

```bash theme={null}
curl -X POST https://api.app.shinzo.ai/auth/platform_keys \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My CI/CD Key"}'
```

Or from your dashboard under **Settings > API Keys**.

<Warning>
  Tokens and API keys are only displayed once at creation. Store them securely as they cannot be retrieved later.
</Warning>

## Endpoint Authentication Requirements

| Endpoint Category                             | Auth Required | Auth Types Accepted         |
| --------------------------------------------- | ------------- | --------------------------- |
| Health (`/health`)                            | ❌             | None                        |
| Auth (`/auth/*`)                              | Varies        | JWT for protected endpoints |
| Telemetry Ingest (`/telemetry/ingest_http/*`) | ✅             | Ingest Token                |
| Telemetry Fetch (`/telemetry/fetch_*`)        | ✅             | JWT                         |
| Agents (`/agent/*`)                           | ✅             | JWT or Platform API Key     |
| Spotlight (`/spotlight/*`)                    | ✅             | JWT or Platform API Key     |
| User (`/user/*`)                              | ✅             | JWT                         |

## Security Best Practices

### Environment Variables

Never hardcode tokens in your source code. Use environment variables:

<CodeGroup>
  ```bash Environment theme={null}
  export SHINZO_JWT_TOKEN="eyJhbGciOiJIUzI1NiIs..."
  export SHINZO_INGEST_TOKEN="abc123-def456-..."
  export SHINZO_API_KEY="sk_shinzo_xyz789..."
  ```

  ```typescript TypeScript theme={null}
  const token = process.env.SHINZO_API_KEY
  ```

  ```python Python theme={null}
  import os
  token = os.getenv("SHINZO_API_KEY")
  ```
</CodeGroup>

### Token Rotation

Regularly rotate tokens to minimize the impact of potential leaks:

1. Create a new token/key with the same permissions
2. Update your applications to use the new token
3. Verify the new token is working
4. Revoke the old token

### Least Privilege

* Use **ingest tokens** for SDK telemetry only
* Use **platform API keys** for server-to-server communication
* Create separate tokens for different environments (dev, staging, prod)

### Monitoring

Monitor token usage in your dashboard:

* Review `last_used_at` timestamps
* Investigate unused tokens
* Revoke tokens that are no longer needed

## Error Responses

### Invalid Token

```json theme={null}
{
  "error": "Invalid or expired token"
}
```

**Status Code:** `401 Unauthorized`

### Missing Token

```json theme={null}
{
  "error": "Authorization header is required"
}
```

**Status Code:** `401 Unauthorized`

### Email Not Verified

```json theme={null}
{
  "error": "Email not verified. Please check your inbox for a verification email."
}
```

**Status Code:** `403 Forbidden`

### Feature Not Enabled

```json theme={null}
{
  "error": "AI Agents feature is not enabled for this account"
}
```

**Status Code:** `403 Forbidden`