Getting Started

Authentication

Two authentication modes are supported:

• API Key (recommended for server-side scripts) — Header Authorization: Bearer sk_live_xxx
• OAuth2 / PKCE (recommended for third-party apps) — authorization_code or client_credentials flow, see OAuth 2.0

curl https://mcp.mextyl.com/v1/crm/contacts \
  -H "Authorization: Bearer sk_live_51Hxxx"

Getting Started

Quickstart Guide

Register for our developer portal and create your Sandbox app to start building against Mextyl's API in minutes.

1. Register for the Developer Portal

Sign in with your existing Mextyl account on the Developer Portal — your developer account is automatically linked to your workspace, no separate signup required. You'll land on My Apps, where every application you register appears with its status (Draft, Sandbox, Pending Review, Production).

2. Create your first app

From My Apps, click + New App and fill out:

• Name — shown to end users when they authorize access
• Description — what your app does
• Company name
• Homepage URL
• Redirect URIs — one or more callback URLs for the Authorization Code flow
• Tool Access — the specific Mextyl tools/endpoints your app can call over REST

3. Save your API credentials

4. Test in Sandbox

Every new app starts in Sandbox mode, pointed at https://mock-api.mextyl.com. It behaves identically to production (same OAuth flow, same response shapes) but returns realistic fake data — safe to experiment with, no real workspace data required.

curl --request POST \
  --url https://mock-api.mextyl.com/v1/sandbox/token

curl --request GET \
  --url https://mock-api.mextyl.com/v1/crm/deals \
  --header 'Authorization: Bearer mxt_sandbox_xxx'

const res = await fetch('https://mock-api.mextyl.com/v1/crm/deals', {
  headers: { Authorization: `Bearer ${process.env.MEXTYL_API_KEY}` }
});
const data = await res.json();
console.log(data);

import requests

resp = requests.get(
    "https://mock-api.mextyl.com/v1/crm/deals",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
print(resp.json())

5. Next steps

• Read the OAuth Workflow guide to implement Authorization Code or Client Credentials in production.
• Browse REST Resources for every endpoint and MCP tool.
• Subscribe to Webhooks to react to events in real time.
• When ready, follow Migrate to Production.

Getting Started

Rate Limits & Errors

Mextyl rate-limits API access to maintain platform stability. Every response includes headers so you can monitor usage and avoid 429 errors.

RateLimit-Limit: 10
RateLimit-Remaining: 9
RateLimit-Reset: 1
X-RateLimit-Limit-Minute: 300
X-RateLimit-Remaining-Minute: 299

HTTP status codes

Getting Started

Error Response Shape

Every error follows the same JSON envelope:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Your token is missing the 'readwrite_crm_deals' scope.",
    "request_id": "req_7f1c2a"
  }
}

Reason codes

OAuth 2.0

Using Mextyl's OAuth Workflow

Mextyl's API uses the OAuth 2.0 open specification to authorize access to our data, supporting both Authorization Code and Client Credentials grant types.

OAuth 2.0

Authorization Code Flow

This flow requires explicit permission from the Mextyl user prior to your app being granted access.

1. Redirect the user to Mextyl

GET https://mcp.mextyl.com/oauth/authorize
    ?response_type=code
    &client_id={CLIENT_ID}
    &redirect_uri={REDIRECT_URI}
    &scope={SCOPES}
    &state={STATE}

2. Mextyl redirects back to your app

{REDIRECT_URI}?code={AUTHORIZATION_CODE}&state={STATE}

3. Exchange the code for an access token

POST https://mcp.mextyl.com/oauth/token
Authorization: Basic {BASE64(client_id:client_secret)}
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={AUTHORIZATION_CODE}
&redirect_uri={REDIRECT_URI}

{
  "access_token": "mxt_at_xxx",
  "expires_in": 3600,
  "refresh_token": "mxt_rt_xxx",
  "scope": "read_crm_contacts read_deal_sourcing",
  "token_type": "Bearer"
}

4. Call the API

curl --request GET \
  --url https://mcp.mextyl.com/v1/crm/contacts \
  --header 'Authorization: Bearer mxt_at_xxx'

OAuth 2.0

Refresh Token Flow

Use this to obtain a new access token without re-prompting the user. Each refresh also rotates the refresh token.

POST https://mcp.mextyl.com/oauth/token
Authorization: Basic {BASE64(client_id:client_secret)}
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={REFRESH_TOKEN}

OAuth 2.0

Client Credentials Flow

Use this when your app only needs access to your own firm's data, with no third-party user in the loop.

POST https://mcp.mextyl.com/oauth/token
Authorization: Basic {BASE64(client_id:client_secret)}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&scope={SCOPES}

{
  "access_token": "mxt_at_xxx",
  "expires_in": 3600,
  "scope": "read_crm_contacts readwrite_deal_sourcing",
  "token_type": "Bearer"
}

OAuth 2.0

Revoking a Token

POST https://mcp.mextyl.com/oauth/revoke
Authorization: Basic {BASE64(client_id:client_secret)}
Content-Type: application/x-www-form-urlencoded

token={TOKEN}
&token_type_hint=access_token

OAuth 2.0

OpenID Connect (OIDC)

Request the openid, profile, and email scopes to receive an id_token alongside your access token, containing basic user claims.

GET https://mcp.mextyl.com/.well-known/openid-configuration

OAuth 2.0

Endpoint Summary

Scopes Reference

User & OpenID Scopes

Scopes Reference

Risk Levels & Approval

Every scope maps to one or more MCP tools carrying a risk level. Tools flagged requiresApproval: true will return 403 requires_approval over REST until a human approves the action from the Mextyl workspace UI — this cannot be bypassed via the API by design.

Model Context Protocol

Claude Desktop Setup

Add Mextyl to your Claude Desktop configuration file:

{
  "mcpServers": {
    "mextyl": {
      "url": "https://mcp.mextyl.com",
      "auth": {
        "type": "oauth2",
        "client_id": "your_client_id"
      }
    }
  }
}

Model Context Protocol

Tools Catalog

Loading tool categories…

Model Context Protocol

Permissions & Scopes

Each tool has a risk level (read, medium, legal, critical) and may require human approval (requiresApproval). Configure per-tool permissions from your console.

Webhooks

Webhooks

Subscribe to real-time events pushed to your endpoint whenever data changes in a workspace your app has been authorized on — no polling required.

Available Event Types

Webhooks

Setting up a Webhook

• Register an endpoint — add an HTTPS URL and select event types.
• Store your signing secret — Mextyl generates a unique whsec_... secret per webhook. Use it to verify payload authenticity.
• Return a 2xx quickly — acknowledge receipt within 5 seconds by returning any 2xx status. Process the payload asynchronously afterward.

Webhooks

Payload Structure

{
  "id": "evt_8f2c1a90",
  "type": "crm.deal.stage_changed",
  "created_at": "2026-05-14T10:32:00Z",
  "enterprise_id": "ent_4471",
  "data": {
    "deal_id": "deal_9931",
    "previous_stage": "screening",
    "new_stage": "due_diligence"
  }
}

Webhooks

Verifying the Signature

Every request includes an X-Mextyl-Signature header: an HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret.

const crypto = require('crypto');

function verifyMextylSignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Webhooks

Retry Policy

Using Postman

Using Postman with Mextyl's API

Import our pre-configured Postman collection and let Postman handle the OAuth token exchange for you.

1. Download the collection

Generate the collection locally against the live gateway:

node scripts/generate-postman.js --url=https://mcp.mextyl.com

This writes api-artifacts/mextyl-api.postman_collection.json and api-artifacts/openapi.json. Or fetch it directly:

curl -o mextyl-api.postman_collection.json \
  https://mcp.mextyl.com/v1/postman-collection.json

Using Postman

Import into Postman

• Import the file — open Postman → Import → Upload Files → select mextyl-api.postman_collection.json.
• Confirm collection name — you'll see "Mextyl API" appear in your Collections sidebar, organized by category (CRM, Deal Sourcing, Cap Table, LP Portal).

Using Postman

Configure OAuth 2.0 in the Collection

Click the collection root → Authorization tab → set:

Using Postman

Get a New Access Token

Click Get New Access Token. A browser window opens for you to authenticate. Once authorized, Postman redirects back and shows Authentication complete. Click Use Token.

Using Postman

Testing Against the Mock Environment

To skip auth entirely and use static mock data, edit the collection's baseUrl variable:

baseUrl = https://mock-api.mextyl.com

No authentication is required against the mock environment — any string works as a Bearer token.

Using Postman

Send a Request

Open any endpoint in the collection, set its Authorization tab to Inherit auth from parent, and click Send. You'll see the live response in Postman's Body panel.

Migrate to Production

Migrate to Production

Pre-requisites and checklist before promoting your app from Sandbox to Live traffic against real Mextyl workspace data.

Requirements

• Fully developed and tested integration in the Sandbox environment (mock-api.mextyl.com).
• Documented rollout plan and expected API traffic volume (requests/day, peak req/s).
• If your app is externally-facing, incorporate approved Mextyl branding assets (logo, "Built with Mextyl" badge).
• Webhook endpoint (if used) publicly reachable over HTTPS with a valid certificate.
• A short demo (video or live walkthrough) of the full integration flow and end-user experience.

Migrate to Production

Promotion Checklist

• Review app details — from My Apps → your app → Actions → Promote to Production, review name, description, redirect URIs, and requested tool access one final time.
• Submit for review — click Submit for Review. Your app moves to Pending Review status. The Mextyl team typically reviews within 1–2 business days.
• Receive approval — upon approval, your app's status becomes Production and it can now request real user authorization against mcp.mextyl.com.
• Rotate credentials if needed — Production apps receive a fresh client_id / client_secret pair, distinct from your Sandbox app. Update your environment variables accordingly.
• Run an internal smoke test — before fully launching, run a small round of internal testing in Production with a real (non-sensitive) account to confirm the full OAuth + API flow behaves as expected.

Migrate to Production

After Launch

• Monitor the RateLimit-* headers on your production traffic and set up alerting before you approach quota.
• Subscribe to updates on API changes to catch breaking changes ahead of time.
• Keep a webhook health check — Mextyl disables webhook endpoints automatically after 7 consecutive days of delivery failures.

SDKs

JavaScript / Node SDK

npm install @mextyl/sdk

SDKs

Python SDK

pip install mextyl