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

# Getting started

> Create an auth link and retrieve the connected account.

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

## Base URL

```text theme={"dark"}
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**.

<Note>
  API keys are only available on Team plan workspaces. Team owners can create multiple keys and revoke them from **Settings > API Keys**.
</Note>

### 2. Send the API Key

Pass the key as a bearer token:

```bash theme={"dark"}
curl https://api.markifact.com/v1/connections/types \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 3. Create an Auth Link

Create a link for the connection type you want the user to authorize.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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. This is the recommended option when your MCP client supports custom headers.

```json theme={"dark"}
{
  "mcpServers": {
    "markifact": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.markifact.com/mcp"
      ],
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN",
        "X-Markifact-Context": "{\"connection_ids\":[\"CONNECTION_ID\"]}"
      }
    }
  }
}
```

If your MCP client does not support custom headers, pass the same restriction in the MCP URL:

```json theme={"dark"}
{
  "mcpServers": {
    "markifact": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.markifact.com/mcp?connection_ids=CONNECTION_ID_1,CONNECTION_ID_2"
      ],
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}
```

The header and query parameter work 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; runtime context can only narrow that access for the request. If you pass `{"connection_ids":[]}` or use `?connection_ids=`, no connection is allowed for that request. Omit runtime context when you want to use the MCP server's normal saved connection settings. If both are provided, `X-Markifact-Context` is used.

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

<Card title="Authentication" icon="key" href="/api-reference/authentication">
  Learn how API keys work and how to pass them with requests.
</Card>

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

```json theme={"dark"}
{
  "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
}
```