Starchild Auth SDK API reference

import { StarchildAuth, StarchildAuthError } from 'starchild-auth-sdk'

const auth = new StarchildAuth({
  clientId: 'YOUR-CLIENT-ID',
  scope: 'profile chat',
  autoLogin: true,
})

Defaults point at production. Override base URLs only when running the full Starchild backend locally.

type UserInfo = {
  userInfoId: string
  agentName: string
  agentAvatar: string
  isGuest: boolean
}

Access tokens last 15 minutes and refresh automatically every 12 minutes and on visibilitychange. Refresh tokens last 7 days and use localStorage key starchild_rt_{clientId}. Never log, transmit, or place a refresh token in a URL.

Flat methods remain available. Namespaced aliases group the same capabilities:

For example, auth.chat.send('hello') is the namespaced equivalent of auth.sendMessage('hello').

sendMessage() and reconnectStream() return a raw Response. Check .ok and read the SSE body yourself. Events include agent_start, text_delta, tool_use, tool_output, agent_end, error, and agent:interrupted. Use reconnectStream(sessionKey) after a dropped stream and cancelRun(threadId) to stop a run.

const response = await auth.chat.send('Hello')
if (!response.ok) throw new Error(`Chat failed: ${response.status}`)
const reader = response.body?.getReader()

Clawd endpoints require the fly-force-instance-id header. The SDK resolves the user's container and injects it automatically. Curl and custom HTTP clients must set it explicitly.

Container deletion returns 403 for OAuth tokens by design.

credit:read enables balance and history methods. credit:write enables top-ups, gift cards, and Points exchange, and implies credit:read. Credit operations can include Stripe checkout, pending and transaction status, KYC, referrals, migration rewards, and WOO bonus. Use an Idempotency-Key for Points exchange and other retryable writes where documented.

JSON helpers throw the exported StarchildAuthError on non-2xx responses:

try {
  await auth.credit.getBalance()
} catch (error) {
  if (error instanceof StarchildAuthError) {
    if (error.insufficientScope) await auth.login()
    console.error(error.status, error.code, error.detail, error.path)
  }
}

The error exposes status, code, detail, path, insufficientScope, and response. A 403 with Insufficient scope means the token lacks an approved scope. A 401 means the token is invalid or expired. Re-authorize with the required scopes instead of treating the two cases as the same.

Popup login works only in a real browser. For server-side or script use, obtain a token in the browser, then inject it without opening a popup:

const auth = new StarchildAuth({ clientId: 'YOUR-CLIENT-ID', autoLogin: false })
;(auth as any)._accessToken = token
const user = await auth.fetchUserInfo()

Keep tokens in server-side secret storage and verify every token with /v1/oauth/userinfo. Do not use browser identity fields as authorization without server verification.

Use two origins deliberately:

1. The Starchild web app may run at http://localhost:6066. This is a Starchild origin and is already handled server-side.
2. Your third-party app runs on its own origin, such as http://localhost:3333. Register that exact origin in the OAuth app. Do not register localhost:6066 as the third-party app.

Browser-versus-Node behavior:

If a new approved origin still fails CORS, check its scheme and port, approval and active status, then allow roughly five minutes for the allowlist refresh.

• Request only the scopes the app needs.
• Keep access tokens out of long-lived application state.
• Never log or transmit refresh tokens.
• Verify every protected request on the server.
• Gate payments and irreversible actions for guest accounts if required.
• Treat StarchildAuthError.insufficientScope separately from 401 expiry.
• Use CSP and sanitize rendered user fields.