API Gateway

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

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:

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:

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

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:

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

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

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

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

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:

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

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)

# 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)

# 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)

# 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)

# 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)

# 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)

# 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)

# 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)

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

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

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
• Documentation
• Community