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.

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

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "uuid": "usr_abc123",
    "email": "user@example.com"
  }
}

Token expiration: 24 hours Header format:

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

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.

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

curl -X POST https://api.app.shinzo.ai/auth/generate_ingest_token \
  -H "Authorization: Bearer <jwt_token>"

Or from your Shinzo Platform dashboard under Settings > Tokens.

Platform API Keys

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

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.

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

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:

export SHINZO_JWT_TOKEN="eyJhbGciOiJIUzI1NiIs..."
export SHINZO_INGEST_TOKEN="abc123-def456-..."
export SHINZO_API_KEY="sk_shinzo_xyz789..."

const token = process.env.SHINZO_API_KEY

import os
token = os.getenv("SHINZO_API_KEY")

Token Rotation

Regularly rotate tokens to minimize the impact of potential leaks:

Create a new token/key with the same permissions
Update your applications to use the new token
Verify the new token is working
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

{
  "error": "Invalid or expired token"
}

Status Code: 401 Unauthorized

Missing Token

{
  "error": "Authorization header is required"
}

Status Code: 401 Unauthorized

Email Not Verified

{
  "error": "Email not verified. Please check your inbox for a verification email."
}

Status Code: 403 Forbidden

Feature Not Enabled

{
  "error": "AI Agents feature is not enabled for this account"
}

Status Code: 403 Forbidden

API Reference Overview Health Check

Overview

Authentication

AI Agents

Agent Messaging

Agent Schedules & Triggers

Agent Channels

Agent Filesystem

MCP Servers

Spotlight

Tokens

Provider Keys

Telemetry

Authentication

Authentication

Authentication Methods

1. JWT Tokens (User Authentication)

2. Ingest Tokens (Telemetry)

3. Platform API Keys (Programmatic Access)

Token Formats

Generating Tokens

JWT Tokens

Ingest Tokens

Platform API Keys

Endpoint Authentication Requirements

Security Best Practices

Environment Variables

Token Rotation

Least Privilege

Monitoring

Error Responses

Invalid Token

Missing Token

Email Not Verified

Feature Not Enabled

​Authentication

​Authentication Methods

​1. JWT Tokens (User Authentication)

​2. Ingest Tokens (Telemetry)

​3. Platform API Keys (Programmatic Access)

​Token Formats

​Generating Tokens

​JWT Tokens

​Ingest Tokens

​Platform API Keys

​Endpoint Authentication Requirements

​Security Best Practices

​Environment Variables

​Token Rotation

​Least Privilege

​Monitoring

​Error Responses

​Invalid Token

​Missing Token

​Email Not Verified

​Feature Not Enabled

Authentication

Authentication Methods

1. JWT Tokens (User Authentication)

2. Ingest Tokens (Telemetry)

3. Platform API Keys (Programmatic Access)

Token Formats

Generating Tokens

JWT Tokens

Ingest Tokens

Platform API Keys

Endpoint Authentication Requirements

Security Best Practices

Environment Variables

Token Rotation

Least Privilege

Monitoring

Error Responses

Invalid Token

Missing Token

Email Not Verified

Feature Not Enabled