Multi-tenancy

The Connection API can be used to connect apps for your users if you're building an app on top of Maton. Create a connection for the app they want to link, render the authorization URL it returns, then call the gateway on their behalf by passing the connection ID.

Connect a user

Create a connection

Create a connection for the app the user wants to link.

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

Fetch the authorization URL

Fetch the connection to get its authorization url.

curl https://api.maton.ai/connections/{connection_id} \
  -H "Authorization: Bearer $MATON_API_KEY"

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "PENDING",
    "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": {}
  }
}

Render the authorization URL

Open the url in an iframe or in a new page. It takes them to a hosted authorization UI where they can sign in to their app account and complete authorization.

The session token in the url is valid for 30 minutes. If it expires, create a connection to get a new url.

Call the gateway on behalf of the user

Once the connection is ACTIVE, call the gateway on their behalf by passing the connection ID in the Maton-Connection header.

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

import os, requests

response = requests.post(
    "https://api.maton.ai/slack/api/chat.postMessage",
    headers={
        "Authorization": f"Bearer {os.environ['MATON_API_KEY']}",
        "Maton-Connection": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    },
    json={"channel": "C0123456", "text": "Hello!"},
)

print(response.json())

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

console.log(await response.json())

Gateway overview

How a request routes through the gateway to a connected app's native API.

Common Questions

No. One API key can create and manage connections for all of your users. You keep them apart by connection_id.

Store the connection_id returned when you create the connection alongside your own user record, and pass it in the Maton-Connection header when you call the gateway.

The connection's status moves to FAILED. Create a new connection and send the user its url to re-authorize — connections can't be re-authorized in place.