Version: 1.1.0

KudosCRM Developer API

The KudosCRM developer API. What you can build with it:

• Apps — your product installs into any workspace through OAuth 2.0 (authorization code + PKCE S256), calls the Data API with its own kat_… tokens, posts its events to the install's own ingest URL and receives the workspace's events as signed v3 envelopes (App events below).
• Personal access tokens — mint and manage scoped bearer tokens (pat_…) for the REST API.
• Outbound webhooks — subscribe your own URL to CRM events (HMAC-signed, retried).
• Ingest — producers POST signed webhook events into the CRM, and read the manifest for schema compatibility.
• Public registry — the listed apps and the scope, event and telephony catalogs, anonymous and cached.

The Marketplace, Installed apps and OAuth consent groups are the API behind KudosCRM's own screens (the marketplace, Connected apps and the consent screen). Your app doesn't need them.

Most endpoints authenticate with a bearer personal access token (Authorization: Bearer pat_…) or, for an installed app, its OAuth access token (Authorization: Bearer kat_…). The ingest endpoints instead authenticate with an HMAC signature over the request body (X-Kudos-Signature: t=<ts>,v1=<hex>) — see the Webhook signing guide. The OAuth server lives at the root of the API host (https://api.kudoscrm.com/oauth/*), not under /api/v1.

Rate limits. Each installed app has an hourly quota (2,400 requests by default); every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window rolls) for it. Any other caller gets 600 requests a minute per session or credential. Every 429 carries Retry-After — the seconds left in the refusing window plus 0–3 s of jitter — and the refusing bucket's headers. Each operation below names its own throttle where it has one.

Try it sends a real request from your browser straight to the production server — nothing is proxied — carrying whatever credential you enter under Authorization. That credential is held in the tab's sessionStorage and is discarded when you close the tab; it is never sent anywhere but the API. Requests count against the same rate limits as any other caller, and writes are real writes. To exercise a local or staging API instead, use your own HTTP client — this hosted reference can only reach the host above.

Authentication

HTTP: Bearer Auth

A personal access token, sent as Authorization: Bearer pat_…. Mint one under Personal access tokens, or in-app at Settings → Platform → API tokens. Read-only when every scope begins with read.

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer
Bearer format:	pat

API Key: HmacSignature

HMAC-SHA256 over <unix_timestamp>.<raw_body> using the source's signing secret — on an installed app's own source, the install's derived key. Stripe-compatible header format. See the Webhook signing guide.

Security Scheme Type:	apiKey
Header parameter name:	X-Kudos-Signature

OAuth 2.0: KudosOAuth

An installed app's OAuth 2.0 access token, sent as Authorization: Bearer kat_…. Obtained with the authorization code flow and PKCE, S256 only (x-pkce: S256): the consent screen is authorizationUrl, the token endpoint tokenUrl (also the refresh URL). Access tokens live one hour; refresh tokens rotate on every use. Each token acts as the install's acting admin, inside the install's grant — catalog keys only, never wildcards; write does not imply read; no scope grants a delete. A token of an uninstalled or disconnected install is 401; a suspended app's 403 app_suspended; a paused install's 503 app_paused with Retry-After: 3600.

Security Scheme Type:

oauth2

OAuth Flow (authorizationCode):

Token URL: https://api.kudoscrm.com/oauth/token Authorization URL: https://app.kudoscrm.com/oauth/authorize Refresh URL: https://api.kudoscrm.com/oauth/token Scopes: contacts:read: Contacts and leads — Contacts, leads and companies in the workspace contacts:write: Contacts — Create and update contacts and companies leads:write: Leads — Create and update leads users:read: Workspace users — Workspace users deals:read: Deals — Deals and pipelines deals:write: Deals — Create and update deals activities:read: Activities — Calls, meetings and notes activities:write: Activities — Log activities tasks:read: Tasks — Tasks tasks:write: Tasks — Create and update tasks tickets:read: Tickets — Support tickets tickets:write: Tickets — Create and update tickets meetings:read: Meetings — Meetings and bookings forms:read: Forms — Forms and submissions quotes:read: Quotes — Quotes imports:read: Imports — Imports emails:read: Email content — Email messages

HTTP: Basic Auth

Client authentication on the token and revoke endpoints: client_id:client_secret (the app_… id and the kcs_… secret from the developer portal), each form-urlencoded, then Base64. Sending client_id and client_secret in the form body instead also works — never both.

Security Scheme Type:	http
HTTP Authorization Scheme:	basic

API Key: CookieSession

A person signed in to the KudosCRM app. Writes also send the kudos_csrf cookie's value in X-CSRF-Token. Used only by KudosCRM's own consent and re-consent screens; an app never calls them.

Security Scheme Type:	apiKey
Cookie parameter name:	kudos_session

Contact

KudosCRM developer support: [email protected]

URL: https://app.kudoscrm.com/docs/

License

Proprietary — KudosCRM terms of service