Skip to main content

​
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": "[email protected]", "password": "your_password"}'
Response: 
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "uuid": "usr_abc123",
    "email": "[email protected]"
  }
}
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 TypeFormatExample
JWT TokenBase64-encoded JWTeyJhbGciOiJIUzI1NiIs...
Ingest TokenUUIDabc123-def456-...
Platform API Keysk_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 CategoryAuth RequiredAuth Types Accepted
Health (/health)NoNone
Auth (/auth/*)VariesJWT for protected endpoints
Telemetry Ingest (/telemetry/ingest_http/*)YesIngest Token
Telemetry Fetch (/telemetry/fetch_*)YesJWT
Agents (/agent/*)YesJWT or Platform API Key
Spotlight (/spotlight/*)YesJWT or Platform API Key
User (/user/*)YesJWT

​
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..."

​
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

{
  "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