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

bash

# Native Slack API call
curl -s -X POST 'https://gateway.maton.ai/slack/api/chat.postMessage' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"channel": "C0123456", "text": "Hello from gateway!"}'

Base URL

code

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

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

Authentication

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

code

Authorization: Bearer YOUR_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:

bash

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

•Sign in or create an account at maton.ai
•Go to maton.ai/settings
•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

bash

curl -s -X GET 'https://ctrl.maton.ai/connections?app=slack&status=ACTIVE' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Query Parameters (optional):

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

Response:

json

{
  "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

bash

curl -s -X POST 'https://ctrl.maton.ai/connections' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"app": "slack"}'

Get Connection

bash

curl -s -X GET 'https://ctrl.maton.ai/connections/21fd90f9-5935-43cd-b6c8-bde9d915ca80' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response:

json

{
  "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

bash

curl -s -X DELETE 'https://ctrl.maton.ai/connections/21fd90f9-5935-43cd-b6c8-bde9d915ca80' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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:

bash

curl -s -X POST 'https://gateway.maton.ai/slack/api/chat.postMessage' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Maton-Connection: 21fd90f9-5935-43cd-b6c8-bde9d915ca80' \
  -d '{"channel": "C0123456", "text": "Hello!"}'

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

Supported Services

Service	App Name	Base URL Proxied
Airtable	`airtable`	`api.airtable.com`
Apollo	`apollo`	`api.apollo.io`
Chargebee	`chargebee`	`{subdomain}.chargebee.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 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 Search Console	`google-search-console`	`www.googleapis.com`
Google Sheets	`google-sheets`	`sheets.googleapis.com`
HubSpot	`hubspot`	`api.hubapi.com`
Jira	`jira`	`api.atlassian.com`
JotForm	`jotform`	`api.jotform.com`
Notion	`notion`	`api.notion.com`
QuickBooks	`quickbooks`	`quickbooks.api.intuit.com`
Salesforce	`salesforce`	`{instance}.salesforce.com`
Shopify	`shopify`	`{subdomain}.myshopify.com` (GraphQL API)
Slack	`slack`	`slack.com`
Stripe	`stripe`	`api.stripe.com`
Typeform	`typeform`	`api.typeform.com`
Xero	`xero`	`api.xero.com`

See references/ for detailed routing guides per provider:

•Airtable - Records, bases, tables
•Apollo - People search, enrichment, contacts
•Chargebee - Subscriptions, customers, invoices
•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 Docs - Document creation, batch updates
•Google Drive - Files, folders, permissions
•Google Forms - Forms, questions, responses
•Gmail - Messages, threads, labels
•Google Search Console - Search analytics, sitemaps
•Google Sheets - Values, ranges, formatting
•HubSpot - Contacts, companies, deals
•Jira - Issues, projects, JQL queries
•JotForm - Forms, submissions, webhooks
•Notion - Pages, databases, blocks
•QuickBooks - Customers, invoices, reports
•Salesforce - SOQL, sObjects, CRUD
•Shopify - Uses GraphQL API (read this first), products, orders, customers
•Slack - Messages, channels, users
•Stripe - Customers, subscriptions, payments
•Typeform - Forms, responses, insights
•Xero - Contacts, invoices, reports

Examples

Slack - Post Message (Native API)

bash

# Native Slack API: POST https://slack.com/api/chat.postMessage
curl -s -X POST 'https://gateway.maton.ai/slack/api/chat.postMessage' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"channel": "C0123456", "text": "Hello!"}'

HubSpot - Create Contact (Native API)

bash

# Native HubSpot API: POST https://api.hubapi.com/crm/v3/objects/contacts
curl -s -X POST 'https://gateway.maton.ai/hubspot/crm/v3/objects/contacts' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "properties": {
      "email": "john@example.com",
      "firstname": "John",
      "lastname": "Doe"
    }
  }'

Google Sheets - Get Spreadsheet Values (Native API)

bash

# Native Sheets API: GET https://sheets.googleapis.com/v4/spreadsheets/{id}/values/{range}
curl -s -X GET 'https://gateway.maton.ai/google-sheets/v4/spreadsheets/122BS1sFN2RKL8AOUQjkLdubzOwgqzPT64KfZ2rvYI4M/values/Sheet1!A1:B2' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Salesforce - SOQL Query (Native API)

bash

# Native Salesforce API: GET https://{instance}.salesforce.com/services/data/v64.0/query?q=...
curl -s -X GET 'https://gateway.maton.ai/salesforce/services/data/v64.0/query?q=SELECT+Id,Name+FROM+Contact+LIMIT+10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Airtable - List Tables (Native API)

bash

# Native Airtable API: GET https://api.airtable.com/v0/meta/bases/{id}/tables
curl -s -X GET 'https://gateway.maton.ai/airtable/v0/meta/bases/appgqan2NzWGP5sBK/tables' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Notion - Query Database (Native API)

bash

# Native Notion API: POST https://api.notion.com/v1/data_sources/{id}/query
curl -s -X POST 'https://gateway.maton.ai/notion/v1/data_sources/23702dc5-9a3b-8001-9e1c-000b5af0a980/query' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Notion-Version: 2025-09-03' \
  -d '{}'

Stripe - List Customers (Native API)

bash

# Native Stripe API: GET https://api.stripe.com/v1/customers
curl -s -X GET 'https://gateway.maton.ai/stripe/v1/customers?limit=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Code Examples

JavaScript (Node.js)

javascript

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

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)
4xx/5xx	Passthrough error from the target API

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

Rate Limits

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

Tips

•
Use native API docs: Refer to each service's official API documentation for endpoint paths and parameters.
•
Headers are forwarded: Custom headers (except Host and Authorization) are forwarded to the target API.
•
Query params work: URL query parameters are passed through to the target API.
•
All HTTP methods supported: GET, POST, PUT, PATCH, DELETE are all supported.
•
QuickBooks special case: Use :realmId in the path and it will be replaced with the connected realm ID.

api-gateway

API Gateway

Quick Start

Base URL

Authentication

Getting Your API Key

Connection Management

List Connections

Create Connection

Get Connection

Delete Connection

Specifying Connection

Supported Services

Examples

Slack - Post Message (Native API)

HubSpot - Create Contact (Native API)

Google Sheets - Get Spreadsheet Values (Native API)

Salesforce - SOQL Query (Native API)

Airtable - List Tables (Native API)

Notion - Query Database (Native API)

Stripe - List Customers (Native API)

Code Examples

JavaScript (Node.js)

Python

Error Handling

Rate Limits

Tips

Optional