Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.markifact.com/llms.txt

Use this file to discover all available pages before exploring further.

Use the Markifact API to create connection links, let users connect external accounts, and retrieve the resulting workspace connections.

​
Base URL

https://api.markifact.com
All API endpoints are under /v1.

​
Quick Connect Flow

​
1. Create an API Key

Team owners can create an API key from the Markifact workspace under Settings > API Keys.
API keys are only available on Team plan workspaces. Team owners can create multiple keys and revoke them from Settings > API Keys.

​
2. Send the API Key

Pass the key as a bearer token: 
curl https://api.markifact.com/v1/connections/types \
  -H "Authorization: Bearer YOUR_API_KEY"
Create a link for the connection type you want the user to authorize. 
curl https://api.markifact.com/v1/connections/auth-link \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_type": "ga4",
    "redirect_url": "https://example.com/oauth/callback",
    "external_id": "customer_123"
  }'
Send the returned url to your user. Auth links expire 24 hours after creation, or once a connection is successfully created — whichever comes first. Generate a new link if it expires or has already been used.

​
4. Get the Connected Account

If you include redirect_url, Markifact sends the user’s browser back to that URL after OAuth. On success, the redirect includes status=success, connection_type, connection_id, and your optional external_id. Use the redirect to update your UI, then fetch the auth link status server-side. When the status is connected, the response includes the created connection. 
curl https://api.markifact.com/v1/connections/auth-links/AUTH_LINK_ID/status \
  -H "Authorization: Bearer YOUR_API_KEY"
You can use the connections endpoints later if you need to look up the connection again by Markifact connection ID, external ID, or type. If you use Markifact MCP from your own app, pass the returned connection_id in X-Markifact-Context to limit the MCP request to that connected account. 
{
  "mcpServers": {
    "markifact": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.markifact.com/mcp"
      ],
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN",
        "X-Markifact-Context": "{\"connection_ids\":[\"1f2e3d4c-0000-0000-0000-000000000000\"]}"
      }
    }
  }
}
The header works in parallel with the MCP server’s saved connection permissions, which you configure in the Markifact UI when creating or editing your MCP server. Saved MCP settings are the maximum allowed access; X-Markifact-Context can only narrow that access for the request. If you pass {"connection_ids":[]}, no connection is allowed for that request. Omit the header when you want to use the MCP server’s normal saved connection settings.

​
API Overview

The first version of the API focuses on connection management:
  • List supported OAuth connection types
  • Create auth links for users to connect accounts
  • Track auth link status
  • List connections by Markifact connection ID, external ID, or type
  • Delete API-visible workspace connections
The API never returns connection credentials.

​
Authentication and Team Scope

Every endpoint requires an API key in the Authorization header. API keys are scoped to the team that created them. Connection endpoints can access shared team connections plus private connections owned by the user who created the API key. Auth link endpoints can only access auth links owned by that team.

Authentication

Learn how API keys work and how to pass them with requests.

​
Connection IDs

Connections returned by the API include an id. This is the public Markifact connection ID and is safe to store in your system. If you pass an external_id when creating an auth link, Markifact stores it on the resulting connection. You can use that value later to find connections that belong to a customer, store, workspace, or account in your own system.

​
Response Format

Responses are JSON. Timestamp fields use Unix time in milliseconds. 
{
  "id": "1f2e3d4c-0000-0000-0000-000000000000",
  "type": "ga4",
  "display_name": "login@example.com",
  "external_id": "customer_123",
  "is_private": false,
  "created_at": 1764000000000,
  "updated_at": 1764000000000
}