Skip to main content

Authentication

The Users API uses two authentication methods depending on the endpoint.

Public Endpoints: App ID Header​

Public endpoints (like POST /v1/users) use the x-app-id header to identify your app:

fetch("https://users-api.brainylab.io/v1/users", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-app-id": "my-app-id", // Your app identifier
  },
  body: JSON.stringify({ email, data }),
});

Requirements:

  • Header name: x-app-id
  • Value: Your app's sourceAppId (1-80 characters, alphanumeric + dots/underscores/hyphens)
  • No password required for public endpoints

Error Handling:

  • Missing header: 400 Bad Request with message "Missing x-app-id header"
  • Invalid format: 400 Bad Request with message "Invalid x-app-id header"

Protected endpoints (like /auth/*) use cookie-based sessions:

1. Login​

First, authenticate with your app credentials:

const response = await fetch("https://users-api.brainylab.io/auth/login", {
  method: "POST",
  headers: {
    "content-type": "application/json",
  },
  credentials: "include", // Important: include cookies
  body: JSON.stringify({
    sourceAppId: "my-app-id",
    password: "your-password",
  }),
});

const data = await response.json();
// { ok: true, sourceAppId: "my-app-id", role: "user" }

After login, the server sets an HTTP-only cookie. Subsequent requests automatically include it:

// List users for your app
const response = await fetch("https://users-api.brainylab.io/auth/users", {
  credentials: "include", // Include session cookie
});

const data = await response.json();
// { users: [...] }

3. Check Session​

Verify your authentication status:

const response = await fetch("https://users-api.brainylab.io/auth/session", {
  credentials: "include",
});

if (response.ok) {
  const data = await response.json();
  // { sourceAppId: "my-app-id", role: "user" }
} else {
  // Not authenticated
}

4. Logout​

End your session:

await fetch("https://users-api.brainylab.io/auth/logout", {
  method: "POST",
  credentials: "include",
});

Session Details​

  • Cookie Name: sid (configurable via SESSION_COOKIE_NAME)
  • Lifetime: 7 days
  • Security: HTTP-only, SameSite=Lax, Secure in production
  • Scope: Per app (sourceAppId)

CORS Configuration​

For browser-based requests, ensure your API instance has CORS configured:

CORS_ORIGINS=https://my-app.example.com,https://another-app.example.com

The API will:

  • Allow requests from listed origins
  • Allow requests without Origin header (non-browser clients)
  • Reject requests from unlisted browser origins

Getting Your App Credentials​

Contact your API administrator to get:

  1. Your sourceAppId (app identifier)
  2. Your password (for dashboard access)

Or, if you're an admin, create apps via:

  • Admin dashboard UI
  • CLI: pnpm add-app <sourceAppId>
  • API: POST /auth/apps (admin only)