api-gateway

name	api-gateway
description	Proxy traffic to upstream APIs with auth, CORS, request/response transforms, rate limiting, monitoring.

API Gateway

Passthrough proxy for direct access to third-party APIs using managed auth connections. The API gateway lets you call native API endpoints directly.

Quick Start

# Native Slack API call
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'channel': 'C0123456', 'text': 'Hello from gateway!'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/slack/api/chat.postMessage', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://gateway.maton.ai/{app}/{native-api-path}

Replace {app} with the service name and {native-api-path} with the actual API endpoint path.

IMPORTANT: The URL path MUST start with the connection's app name (eg. /google-mail/...). This prefix tells the gateway which app connection to use. For example, the native Gmail API path starts with gmail/v1/, so full paths look like /google-mail/gmail/v1/users/me/messages.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

The API gateway automatically injects the appropriate OAuth token for the target service.

Environment Variable: You can set your API key as the MATON_API_KEY environment variable:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Click the copy button on the right side of API Key section to copy it

Connection Management

Connection management uses a separate base URL: https://ctrl.maton.ai

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=slack&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Query Parameters (optional):

• app - Filter by service name (e.g., slack, hubspot, salesforce)
• status - Filter by connection status (ACTIVE, PENDING, FAILED)

Response:

{
  "connections": [
    {
      "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
      "status": "ACTIVE",
      "creation_time": "2025-12-08T07:20:53.488460Z",
      "last_updated_time": "2026-01-31T20:03:32.593153Z",
      "url": "https://connect.maton.ai/?session_token=5e9...",
      "app": "slack",
      "metadata": {}
    }
  ]
}

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'slack'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=5e9...",
    "app": "slack",
    "metadata": {}
  }
}

Open the returned URL in a browser to complete OAuth.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple connections for the same app, you can specify which connection to use by adding the Maton-Connection header with the connection ID:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'channel': 'C0123456', 'text': 'Hello!'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/slack/api/chat.postMessage', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection for that app.

Supported Services

Service	App Name	Base URL Proxied
ActiveCampaign	active-campaign	{account}.api-us1.com
Acuity Scheduling	acuity-scheduling	acuityscheduling.com
Airtable	airtable	api.airtable.com
Apollo	apollo	api.apollo.io
Asana	asana	app.asana.com
Attio	attio	api.attio.com
Basecamp	basecamp	3.basecampapi.com
beehiiv	beehiiv	api.beehiiv.com
Box	box	api.box.com
Brevo	brevo	api.brevo.com
Calendly	calendly	api.calendly.com
CallRail	callrail	api.callrail.com
Chargebee	chargebee	{subdomain}.chargebee.com
ClickFunnels	clickfunnels	{subdomain}.myclickfunnels.com
ClickSend	clicksend	rest.clicksend.com
ClickUp	clickup	api.clickup.com
Cognito Forms	cognito-forms	www.cognitoforms.com
Constant Contact	constant-contact	api.cc.email
Dropbox	dropbox	api.dropboxapi.com
Eventbrite	eventbrite	www.eventbriteapi.com
Fathom	fathom	api.fathom.ai
Fireflies	fireflies	api.fireflies.ai
GitHub	github	api.github.com
Gumroad	gumroad	api.gumroad.com
Google Ads	google-ads	googleads.googleapis.com
Google Analytics Admin	google-analytics-admin	analyticsadmin.googleapis.com
Google Analytics Data	google-analytics-data	analyticsdata.googleapis.com
Google Calendar	google-calendar	www.googleapis.com
Google Contacts	google-contacts	people.googleapis.com
Google Docs	google-docs	docs.googleapis.com
Google Drive	google-drive	www.googleapis.com
Google Forms	google-forms	forms.googleapis.com
Gmail	google-mail	gmail.googleapis.com
Google Merchant	google-merchant	merchantapi.googleapis.com
Google Meet	google-meet	meet.googleapis.com
Google Play	google-play	androidpublisher.googleapis.com
Google Search Console	google-search-console	www.googleapis.com
Google Sheets	google-sheets	sheets.googleapis.com
Google Slides	google-slides	slides.googleapis.com
Google Tasks	google-tasks	tasks.googleapis.com
Google Workspace Admin	google-workspace-admin	admin.googleapis.com
HubSpot	hubspot	api.hubapi.com
Jira	jira	api.atlassian.com
Jobber	jobber	api.getjobber.com
JotForm	jotform	api.jotform.com
Keap	keap	api.infusionsoft.com
Kit	kit	api.kit.com
Klaviyo	klaviyo	a.klaviyo.com
Linear	linear	api.linear.app
LinkedIn	linkedin	api.linkedin.com
Mailchimp	mailchimp	{dc}.api.mailchimp.com
MailerLite	mailerlite	connect.mailerlite.com
ManyChat	manychat	api.manychat.com
Microsoft Excel	microsoft-excel	graph.microsoft.com
Microsoft To Do	microsoft-to-do	graph.microsoft.com
Monday.com	monday	api.monday.com
Notion	notion	api.notion.com
OneDrive	one-drive	graph.microsoft.com
Outlook	outlook	graph.microsoft.com
Pipedrive	pipedrive	api.pipedrive.com
QuickBooks	quickbooks	quickbooks.api.intuit.com
Quo	quo	api.openphone.com
Salesforce	salesforce	{instance}.salesforce.com
SignNow	signnow	api.signnow.com
Slack	slack	slack.com
Square	squareup	connect.squareup.com
Stripe	stripe	api.stripe.com
Systeme.io	systeme	api.systeme.io
Tally	tally	api.tally.so
Telegram	telegram	api.telegram.org
TickTick	ticktick	api.ticktick.com
Todoist	todoist	api.todoist.com
Trello	trello	api.trello.com
Twilio	twilio	api.twilio.com
Typeform	typeform	api.typeform.com
Vimeo	vimeo	api.vimeo.com
WhatsApp Business	whatsapp-business	graph.facebook.com
WooCommerce	woocommerce	{store-url}/wp-json/wc/v3
WordPress.com	wordpress	public-api.wordpress.com
Xero	xero	api.xero.com
YouTube	youtube	www.googleapis.com
Zoho Bigin	zoho-bigin	www.zohoapis.com
Zoho Books	zoho-books	www.zohoapis.com
Zoho Calendar	zoho-calendar	calendar.zoho.com
Zoho CRM	zoho-crm	www.zohoapis.com
Zoho Inventory	zoho-inventory	www.zohoapis.com
Zoho Mail	zoho-mail	mail.zoho.com
Zoho People	zoho-people	people.zoho.com
Zoho Recruit	zoho-recruit	recruit.zoho.com

See references/ for detailed routing guides per provider:

• ActiveCampaign - Contacts, deals, tags, lists, automations, campaigns
• Acuity Scheduling - Appointments, calendars, clients, availability
• Airtable - Records, bases, tables
• Apollo - People search, enrichment, contacts
• Asana - Tasks, projects, workspaces, webhooks
• Attio - People, companies, records, tasks
• Basecamp - Projects, to-dos, messages, schedules, documents
• beehiiv - Publications, subscriptions, posts, custom fields
• Box - Files, folders, collaborations, shared links
• Brevo - Contacts, email campaigns, transactional emails, templates
• Calendly - Event types, scheduled events, availability, webhooks
• CallRail - Calls, trackers, companies, tags, analytics
• Chargebee - Subscriptions, customers, invoices
• ClickFunnels - Contacts, products, orders, courses, webhooks
• ClickSend - SMS, MMS, voice messages, contacts, lists
• ClickUp - Tasks, lists, folders, spaces, webhooks
• Cognito Forms - Forms, entries, documents, files
• Constant Contact - Contacts, email campaigns, lists, segments
• Dropbox - Files, folders, search, metadata, revisions, tags
• Eventbrite - Events, venues, tickets, orders, attendees
• Fathom - Meeting recordings, transcripts, summaries, webhooks
• Fireflies - Meeting transcripts, summaries, AskFred AI, channels
• GitHub - Repositories, issues, pull requests, commits
• Gumroad - Products, sales, subscribers, licenses, webhooks
• Google Ads - Campaigns, ad groups, GAQL queries
• Google Analytics Admin - Reports, dimensions, metrics
• Google Analytics Data - Reports, dimensions, metrics
• Google Calendar - Events, calendars, free/busy
• Google Contacts - Contacts, contact groups, people search
• Google Docs - Document creation, batch updates
• Google Drive - Files, folders, permissions
• Google Forms - Forms, questions, responses
• Gmail - Messages, threads, labels
• Google Meet - Spaces, conference records, participants
• Google Merchant - Products, inventories, promotions, reports
• Google Play - In-app products, subscriptions, reviews
• Google Search Console - Search analytics, sitemaps
• Google Sheets - Values, ranges, formatting
• Google Slides - Presentations, slides, formatting
• Google Tasks - Task lists, tasks, subtasks
• Google Workspace Admin - Users, groups, org units, domains, roles
• HubSpot - Contacts, companies, deals
• Jira - Issues, projects, JQL queries
• Jobber - Clients, jobs, invoices, quotes (GraphQL)
• JotForm - Forms, submissions, webhooks
• Keap - Contacts, companies, tags, tasks, opportunities, campaigns
• Kit - Subscribers, tags, forms, sequences, broadcasts
• Klaviyo - Profiles, lists, campaigns, flows, events
• Linear - Issues, projects, teams, cycles (GraphQL)
• LinkedIn - Profile, posts, shares, media uploads
• Mailchimp - Audiences, campaigns, templates, automations
• MailerLite - Subscribers, groups, campaigns, automations, forms
• ManyChat - Subscribers, tags, flows, messaging
• Microsoft Excel - Workbooks, worksheets, ranges, tables, charts
• Microsoft To Do - Task lists, tasks, checklist items, linked resources
• Monday.com - Boards, items, columns, groups (GraphQL)
• Notion - Pages, databases, blocks
• OneDrive - Files, folders, drives, sharing
• Outlook - Mail, calendar, contacts
• Pipedrive - Deals, persons, organizations, activities
• QuickBooks - Customers, invoices, reports
• Quo - Calls, messages, contacts, conversations, webhooks
• Salesforce - SOQL, sObjects, CRUD
• SignNow - Documents, templates, invites, e-signatures
• SendGrid - Email sending, contacts, templates, suppressions, statistics
• Slack - Messages, channels, users
• Square - Payments, customers, orders, catalog, inventory, invoices
• Stripe - Customers, subscriptions, payments
• Systeme.io - Contacts, tags, courses, communities, webhooks
• Tally - Forms, submissions, workspaces, webhooks
• Telegram - Messages, chats, bots, updates, polls
• TickTick - Tasks, projects, task lists
• Todoist - Tasks, projects, sections, labels, comments
• Trello - Boards, lists, cards, checklists
• Twilio - SMS, voice calls, phone numbers, messaging
• Typeform - Forms, responses, insights
• Vimeo - Videos, folders, albums, comments, likes
• WhatsApp Business - Messages, templates, media
• WooCommerce - Products, orders, customers, coupons
• WordPress.com - Posts, pages, sites, users, settings
• Xero - Contacts, invoices, reports
• YouTube - Videos, playlists, channels, subscriptions
• Zoho Bigin - Contacts, companies, pipelines, products
• Zoho Books - Invoices, contacts, bills, expenses
• Zoho Calendar - Calendars, events, attendees, reminders
• Zoho CRM - Leads, contacts, accounts, deals, search
• Zoho Inventory - Items, sales orders, invoices, purchase orders, bills
• Zoho Mail - Messages, folders, labels, attachments
• Zoho People - Employees, departments, designations, attendance, leave
• Zoho Recruit - Candidates, job openings, interviews, applications

Examples

Slack - Post Message (Native API)

# Native Slack API: POST https://slack.com/api/chat.postMessage
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'channel': 'C0123456', 'text': 'Hello!'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/slack/api/chat.postMessage', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json; charset=utf-8')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

HubSpot - Create Contact (Native API)

# Native HubSpot API: POST https://api.hubapi.com/crm/v3/objects/contacts
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'properties': {'email': '[e-mail]', 'firstname': 'John', 'lastname': 'Doe'}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/hubspot/crm/v3/objects/contacts', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Google Sheets - Get Spreadsheet Values (Native API)

# Native Sheets API: GET https://sheets.googleapis.com/v4/spreadsheets/{id}/values/{range}
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-sheets/v4/spreadsheets/122BS1sFN2RKL8AOUQjkLdubzOwgqzPT64KfZ2rvYI4M/values/Sheet1!A1:B2')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Salesforce - SOQL Query (Native API)

# Native Salesforce API: GET https://{instance}.salesforce.com/services/data/v64.0/query?q=...
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/salesforce/services/data/v64.0/query?q=SELECT+Id,Name+FROM+Contact+LIMIT+10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Airtable - List Tables (Native API)

# Native Airtable API: GET https://api.airtable.com/v0/meta/bases/{id}/tables
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/airtable/v0/meta/bases/appgqan2NzWGP5sBK/tables')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Notion - Query Database (Native API)

# Native Notion API: POST https://api.notion.com/v1/data_sources/{id}/query
python <<'EOF'
import urllib.request, os, json
data = json.dumps({}).encode()
req = urllib.request.Request('https://gateway.maton.ai/notion/v1/data_sources/23702dc5-9a3b-8001-9e1c-000b5af0a980/query', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Notion-Version', '2025-09-03')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Stripe - List Customers (Native API)

# Native Stripe API: GET https://api.stripe.com/v1/customers
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/stripe/v1/customers?limit=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Code Examples

JavaScript (Node.js)

const response = await fetch('https://gateway.maton.ai/slack/api/chat.postMessage', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`
  },
  body: JSON.stringify({ channel: 'C0123456', text: 'Hello!' })
});

Python

import os
import requests

response = requests.post(
    'https://gateway.maton.ai/slack/api/chat.postMessage',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={'channel': 'C0123456', 'text': 'Hello!'}
)

Error Handling

Status	Meaning
400	Missing connection for the requested app
401	Invalid or missing Maton API key
429	Rate limited (10 requests/second per account)
500	Internal Server Error
4xx/5xx	Passthrough error from the target API

Errors from the target API are passed through with their original status codes and response bodies.

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

1. Verify your URL path starts with the correct app name. The path must begin with /google-mail/. For example:

• Correct: https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages
• Incorrect: https://gateway.maton.ai/gmail/v1/users/me/messages

2. Ensure you have an active connection for the app. List your connections to verify:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-mail&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Server Error

A 500 error may indicate an expired OAuth token. Try creating a new connection via the Connection Management section above and completing OAuth authorization. If the new connection is "ACTIVE", delete the old connection to ensure the gateway uses the new one.

Rate Limits

• 10 requests per second per account
• Target API rate limits also apply

Notes

• When using curl with URLs containing brackets (fields[], sort[], records[]), use the -g flag to disable glob parsing
• When piping curl output to jq, environment variables may not expand correctly in some shells, which can cause "Invalid API key" errors

Tips

1. Use native API docs: Refer to each service's official API documentation for endpoint paths and parameters.

2. Headers are forwarded: Custom headers (except Host and Authorization) are forwarded to the target API.

3. Query params work: URL query parameters are passed through to the target API.

4. All HTTP methods supported: GET, POST, PUT, PATCH, DELETE are all supported.

5. QuickBooks special case: Use :realmId in the path and it will be replaced with the connected realm ID.

Optional

• Github
• API Reference
• Maton Community
• Maton Support