Authentication

Uchara provides three authentication methods for different use cases:

1. Widget Token → JWT (Visitor SDK)

Use Case: Embedding chat widget in customer-facing applications

Flow:

1. Get widget token from channel settings (public, embedded in HTML)
2. Client calls POST /v1/widget/session with widget token
3. Server creates/retrieves contact, returns short-lived JWT (24h)
4. Client uses JWT for subsequent REST + WebSocket requests

Security:

• Widget token is public (safe to embed in client-side code)
• JWT is scoped to single contact
• No sensitive operations allowed

Example:

const visitor = new VisitorSDK({
  apiURL: 'https://api.uchara.com',
  widgetToken: 'wgt_abc123', // Public token
});

await visitor.init(); // Gets JWT, stores internally

2. Email/Password → JWT (Agent SDK)

Use Case: Building custom agent dashboards

Flow:

1. Client calls POST /v1/auth/login with email/password
2. Server validates credentials, returns access + refresh tokens
3. Access token expires in 1h, refresh token in 30d
4. Client refreshes with POST /v1/auth/refresh

Security:

• Credentials transmitted over HTTPS only
• Access token short-lived (1h)
• Refresh token stored securely (httpOnly cookie or secure storage)

Example:

agent = AgentSDK(api_url="https://api.uchara.com")
response = agent.login(
    email="agent@company.com",
    password="..."
)
# Access token auto-set, refresh handled by SDK

3. API Key (Server SDK)

Use Case: Backend-to-backend integration

Flow:

1. Generate API key in workspace settings (admin only)
2. Client sends API key in Authorization: Bearer <key> header
3. Server validates key, extracts workspace context

Security:

• API key is secret — never commit to git, use env vars
• Scoped to workspace, full permissions
• Rotate regularly (90 days recommended)
• Can be revoked instantly

Key Format: uchara_sk_<32_random_chars>

Example:

client := uchara.NewServerSDK(uchara.ServerConfig{
    APIURL: "https://api.uchara.com",
    APIKey: os.Getenv("UCHARA_API_KEY"),
})

Generating API Keys

API keys can be generated from the workspace settings:

# Via API (requires admin JWT)
POST /v1/admin/api-keys
{
  "name": "Production Server",
  "expires_at": "2027-12-31T23:59:59Z"
}

# Response (key shown only once!)
{
  "id": "...",
  "key": "uchara_sk_abc123...",
  "key_prefix": "uchara_sk_ab...",
  "created_at": "..."
}

Best Practices

Visitor SDK

• Call init() once on app start
• JWT expires in 24h — SDK handles refresh automatically
• Store widget token in config, not hardcoded

Agent SDK

• Store refresh token securely (keychain/keystore on mobile)
• Implement token refresh before expiry (proactive, not reactive)
• Clear tokens on logout

Server SDK

• Load API key from environment variables
• Rotate keys every 90 days
• Use separate keys for staging/production
• Revoke compromised keys immediately

Token Expiry

Token Type	Lifetime	Refresh
Visitor JWT	24 hours	Auto on init()
Agent Access Token	1 hour	Via refresh token
Agent Refresh Token	30 days	Re-login required
API Key	Custom (default: no expiry)	Rotate manually

Error Handling

All SDKs normalize authentication errors:

try {
  await sdk.sendMessage(conversationId, { content: 'Hello' });
} catch (error) {
  if (error.status === 401) {
    // Token expired, re-authenticate
    await sdk.login(...);
  }
}

Security Considerations

1. Never commit secrets - Use environment variables
2. HTTPS only - All requests over TLS
3. Rotate regularly - API keys every 90 days
4. Scope appropriately - Use least privilege
5. Monitor usage - Track API key last_used_at
6. Revoke on breach - Instant revocation via API

Next Steps

• Quick Start Guide
• REST API Reference
• SDK Overview