Authentication & API keys
Every request authenticates with an API key created in your workspace settings. Keys are prefixed medal_ and scoped to a single workspace.
On this page
new Medal(token, options?)
Pass the API key; options cover baseUrl, timeout, and workspaceId for multi-workspace tokens.
import { Medal } from '@medalsocial/sdk';
const medal = new Medal(process.env.MEDAL_API_KEY as string, {
timeout: 15_000,
});Idempotency keys
Idempotency key sent as the Idempotency-Key header. Retries with the same key return the original result instead of repeating the operation. Required by some endpoints for capability-scoped tokens (e.g. helpdesk replies, webhook creation).
await medal.webhooks.create(
{ name: 'CRM sync', url: 'https://example.com/hooks', event_types: ['contact.created'] },
{ idempotencyKey: 'crm-sync-setup-1' }
);Capability confirmations
Capability confirmation token sent as the X-Capability-Confirmation header. Required alongside idempotencyKey when a token granted a capability-style scope directly (e.g. helpdesk.webhook.manage) executes a confirmable write route. API keys with legacy scopes do not need it.
medal.workspaces.list()
List workspaces accessible to the current API key or OAuth token.
list(): Promise<ApiResponse<Workspace[]>>