Authentication

Authentication Guide

EEv3 supports multiple authentication methods. Choose the right one for your use case: API keys for server-to-server, OAuth for user-facing apps, scoped tokens for fine-grained access, and JWT for webhook verification.

API Key Authentication

The simplest method. Include your API key in the Authorization header as a Bearer token. Keys start with sk_live_ for production and sk_test_ for sandbox.

import { createClient } from '@evileye/sdk'

const ee = createClient({
  token: process.env.EE_TOKEN!, // sk_live_...
  entity: 'my-company',
})

// All subsequent calls are authenticated
const result = await ee.ai.generate({ prompt: 'Hello' })

OAuth 2.0 Flow

For user-facing applications where users grant permission to your app. EEv3 supports the Authorization Code flow with PKCE.

// 1. Redirect user to authorize
const authUrl = ee.auth.getOAuthUrl({
  provider: 'google',
  redirectUri: 'https://myapp.com/callback',
  scopes: ['ai.generate', 'storage.read'],
})

// 2. Exchange code for token in your callback
const { accessToken, refreshToken } = await ee.auth.exchangeCode({
  code: req.query.code,
  redirectUri: 'https://myapp.com/callback',
})

// 3. Use the access token
const userClient = createClient({
  token: accessToken,
  entity: 'my-company',
})

Scoped Tokens

Scoped tokens provide fine-grained access control. They are limited to specific faces (28 of 42 faces support scoping), specific entities, and have configurable expiry. Use them in client-side code or multi-tenant scenarios.

// Create a scoped token with limited permissions
const scoped = await ee.auth.createScopedToken({
  scopes: ['storage.read', 'storage.write'],
  entityId: 'tenant-abc',
  expiresIn: '1h', // time-limited
})

// Use in client-safe contexts
// scoped.token = 'st_...'

JWT Verification

Incoming webhooks are signed with a JWT. Use the SDK's verify function to validate the signature before processing.

import { verify } from '@evileye/sdk/webhooks'

// Verify incoming webhook JWT
const payload = verify(req.headers['x-ee-signature'], {
  secret: process.env.EE_WEBHOOK_SECRET!,
})

if (!payload) {
  return res.status(401).json({ error: 'Invalid signature' })
}

Best Practices

• Rotate keys regularly — set up key rotation on a 90-day cycle
• Use scoped tokens — prefer scoped tokens over full API keys for client-side code
• Never expose keys in client code — API keys are server-only; use scoped tokens for the browser
• Use environment variables — never hardcode tokens in source code
• Monitor key usage — the dashboard shows per-key usage stats and anomaly alerts

Related

• Webhooks— webhook events and signature verification
• Scoped Tokens— deep dive into the 28 scoped-token faces