Does Maton store any request data?

Gateway

The gateway proxies your requests to a connected app's native API. When you call the gateway, Maton looks up the connection, injects the app credentials, and forwards the request to the upstream API.

Routing

Prefix any native API path with the app identifier:

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

The first path segment selects the target app. Everything after it including query string is forwarded to the upstream API.

# Slack — GET https://slack.com/api/conversations.list
curl "https://api.maton.ai/slack/api/conversations.list?types=public_channel&limit=10" \
  -H "Authorization: Bearer $MATON_API_KEY"

# Gmail — GET https://gmail.googleapis.com/gmail/v1/users/me/messages
curl "https://api.maton.ai/google-mail/gmail/v1/users/me/messages" \
  -H "Authorization: Bearer $MATON_API_KEY"

// POST https://api.hubapi.com/crm/v3/objects/contacts/search
const response = await fetch(
  'https://api.maton.ai/hubspot/crm/v3/objects/contacts/search',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.MATON_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ properties: ['email', 'firstname'], limit: 10 }),
  }
)

import os, requests

# POST https://api.hubapi.com/crm/v3/objects/contacts/search
response = requests.post(
    "https://api.maton.ai/hubspot/crm/v3/objects/contacts/search",
    headers={"Authorization": f"Bearer {os.environ['MATON_API_KEY']}"},
    json={"properties": ["email", "firstname"], "limit": 10},
)

Refer to each service's official API documentation for its endpoint paths and parameters.

Path Placeholders

For apps that require account-specific identifiers in the path, put the literal placeholder (eg. :realmId for QuickBooks) in the path and the gateway substitutes the connected account's value:

curl "https://api.maton.ai/quickbooks/v3/company/:realmId/query?query=SELECT%20*%20FROM%20Customer" \
  -H "Authorization: Bearer $MATON_API_KEY"

Specifying connection

The gateway allows you to specify a connection if you have multiple connections for an app. Pass the connection ID in the Maton-Connection header. When omitted, the gateway uses the oldest ACTIVE connection by default.

curl "https://api.maton.ai/slack/api/conversations.list?types=public_channel&limit=10" \
  -H "Authorization: Bearer $MATON_API_KEY" \
  -H "Maton-Connection: 21fd90f9-5935-43cd-b6c8-bde9d915ca80"

import os, requests

response = requests.get(
    "https://api.maton.ai/slack/api/conversations.list?types=public_channel&limit=10",
    headers={
        "Authorization": f"Bearer {os.environ['MATON_API_KEY']}",
        "Maton-Connection": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    },
)

print(response.json())

const response = await fetch(
  'https://api.maton.ai/slack/api/conversations.list?types=public_channel&limit=10',
  {
    headers: {
      Authorization: `Bearer ${process.env.MATON_API_KEY}`,
      'Maton-Connection': '21fd90f9-5935-43cd-b6c8-bde9d915ca80',
    },
  }
)

console.log(await response.json())

Every response names the connection it used in a Maton-Connection header, so you can send that value back to keep later requests on the same account. When you omit the header and the app has more than one ACTIVE connection, the response also includes an X-Maton-Hint header saying which connection was chosen.

200 OK
Maton-Connection: 21fd90f9-5935-43cd-b6c8-bde9d915ca80
X-Maton-Hint: Used connection `21fd90f9-5935-43cd-b6c8-bde9d915ca80`, the oldest of 2 active `slack` connections. Send the `Maton-Connection` header to use another one.

If the connection in Maton-Connection can't be used, the gateway rejects the request before calling the app:

404 when the ID isn't one of your connections. A truncated ID that matches one of your connections is completed for you in the message.
400 when the connection is FAILED or PENDING, or belongs to a different app.

The error message names your ACTIVE connections for the app, so you can retry with one of them. If there are none, it says how to reconnect or create one.

Finding connection ID

List your connections for an app, filtering by ACTIVE status. Use the connection's metadata to tell accounts apart, which holds identifying details such as email or workspace name.

curl "https://api.maton.ai/connections?app=slack&status=ACTIVE" \
  -H "Authorization: Bearer $MATON_API_KEY"

{
  "connections": [
    {
      "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
      "status": "ACTIVE",
      "app": "slack",
      "method": "OAUTH2",
      "metadata": {
        "team": "Acme Workspace"
      }
    }
  ]
}

Common Questions

We store request metadata such as the URL, method, and headers for operational purposes. We never store request or response bodies.

Functions

Deploy your code to Maton and run it as an HTTP endpoint with access to your connected apps.

Triggers

Subscribe to events from a connected app and deliver each one to your webhook destinations.