AuthService SDK

Endpoint headers

• POST /v1/auth/signup, POST /v1/auth/login, POST /v1/auth/google, GET /v1/projects/config, GET /v1/plans -> send X-Public-Key.
• GET /v1/auth/me, POST /v1/auth/logout, POST /v1/plans/{planId}/subscribe, GET /v1/user/subscription, DELETE /v1/user/subscription, GET /v1/user/roles, GET /v1/user/permissions -> send X-Secret-Key plus the active session token (X-Session-Id or sdk_session cookie).
• Cookie-protected endpoints (/v1/auth/me, /v1/auth/logout, /v1/plans/{planId}/subscribe, /v1/user/subscription, /v1/user/roles, /v1/user/permissions) require the sdk_csrf cookie echoed in the X-CSRF-Token header. The SDK stores the CSRF token from auth responses under auth_csrf_token_${scope} and reuses it if the cookie is not readable.

Sessions & cookies

• Sessions last 24h; the SDK stores session tokens per project scope and reuses the signed value returned by the API or the pre-set sdk_session cookie.
• Requests always include credentials so sdk_session/sdk_csrf cookies travel with the call.
• Session data is never shared across projects (projectId/publicKey/secretKey/apiUrl are used to namespace the persisted session).

RBAC checks

• has({ role }) and has({ permission }) query the logged-in user's roles/permissions for the current project.
• For tenant-aware checks, ensure the SDK is configured with the correct project scope (projectId or keys) per tenant.

State sync

• The SDK caches currentPlan, subscription, roles, and permissions per project scope in memory and localStorage.
• Access the cached values through getState() and rely on the SDK to sync them when it receives API responses.

Error handling

• 401/403 → generic reauthentication error and session reset.
• 429 → exponential backoff respecting Retry-After when present, then a generic rate-limit error.
• Other errors are surfaced with a generic message while preserving details when available.

Example

import { createAuthClient } from "@authservice/sdk";

const auth = createAuthClient({
  projectId: "proj_123",
  publicKey: "pk_live_123",
  secretKey: "sk_live_123",
  apiUrl: "https://api.your-auth.com",
});

await auth.signIn({ email: "[email protected]", password: "secret" });
const me = await auth.getUser(); // uses X-Secret-Key + X-CSRF-Token and current session