Open Markdown · Agent index

Authentication and identity

Management API credentials and widget customer identity solve different problems. Keep management keys and provider secrets on a trusted backend.

Organization API keys

Create a key for the intended organization in the dashboard's developer settings. Use the permissions needed for the integration. The current organization API verifies keys sent in X-API-Key; an organization key is not a Bearer session token. Every organization operation requires an orgId matching the key's organization. A successful schema request does not prove permission to read or mutate resources.

A server-side read against the supported REST endpoint:

const apiKey = process.env.MASHEEV_API_KEY;
const orgId = process.env.MASHEEV_ORG_ID;
if (!apiKey || !orgId) throw new Error("Configure MASHEEV_API_KEY and MASHEEV_ORG_ID");

const url = new URL("https://api.masheev.com/api/rpc/inboxes");
url.searchParams.set("orgId", orgId);
const response = await fetch(url, {
  headers: { "X-API-Key": apiKey },
  signal: AbortSignal.timeout(10_000),
});
if (!response.ok) throw new Error(`Masheev request failed: ${response.status}`);
const { inboxes } = await response.json();

Use the OpenAPI reference for exact endpoint paths, inputs and outputs. Validate access with a read before provisioning. Do not log authorization headers or a full response containing customer information.

Browser sessions

The dashboard uses Better Auth sessions. Browser session APIs are appropriate only when the user is signed in to Masheev and the deployment's cookie/origin behavior supports it. Signing into your own application does not create a Masheev session. Do not put a management key in client JavaScript to work around this difference.

Signed widget identity

An inbox ID is public configuration. The inbox's HMAC secret is private. Generate userHash on your backend from the authenticated application user's ID:

import { createHmac } from "node:crypto";

// authenticatedUser must come from your server's existing session validation.
const userHash = createHmac("sha256", inboxSecret)
  .update(authenticatedUser.id)
  .digest("hex");

Pass userId and userHash in the SDK's user configuration. The signature endpoint must derive the user from the session, not trust an arbitrary submitted ID. Only include profile fields needed for support. Test logout and account switching so the next user cannot see the previous user's conversation.

Secret placement

Use placeholder names in .env.example. Never prefix a management key with a framework's public environment prefix. See API client for known server transport limitations and MCP for its separate authentication path.