Create auth link

curl --request POST \
  --url https://api.markifact.com/v1/connections/auth-link \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "connection_type": "ga4",
  "redirect_url": "https://example.com/oauth/callback",
  "external_id": "customer_123",
  "is_private": false
}
'

import requests

url = "https://api.markifact.com/v1/connections/auth-link"

payload = {
    "connection_type": "ga4",
    "redirect_url": "https://example.com/oauth/callback",
    "external_id": "customer_123",
    "is_private": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    connection_type: 'ga4',
    redirect_url: 'https://example.com/oauth/callback',
    external_id: 'customer_123',
    is_private: false
  })
};

fetch('https://api.markifact.com/v1/connections/auth-link', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.markifact.com/v1/connections/auth-link",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'connection_type' => 'ga4',
    'redirect_url' => 'https://example.com/oauth/callback',
    'external_id' => 'customer_123',
    'is_private' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.markifact.com/v1/connections/auth-link"

	payload := strings.NewReader("{\n  \"connection_type\": \"ga4\",\n  \"redirect_url\": \"https://example.com/oauth/callback\",\n  \"external_id\": \"customer_123\",\n  \"is_private\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.markifact.com/v1/connections/auth-link")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"connection_type\": \"ga4\",\n  \"redirect_url\": \"https://example.com/oauth/callback\",\n  \"external_id\": \"customer_123\",\n  \"is_private\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.markifact.com/v1/connections/auth-link")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"connection_type\": \"ga4\",\n  \"redirect_url\": \"https://example.com/oauth/callback\",\n  \"external_id\": \"customer_123\",\n  \"is_private\": false\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "url": "<string>",
  "expires_at": 123
}

{
  "detail": "<unknown>"
}

POST

connections

auth-link

Create auth link

curl --request POST \
  --url https://api.markifact.com/v1/connections/auth-link \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "connection_type": "ga4",
  "redirect_url": "https://example.com/oauth/callback",
  "external_id": "customer_123",
  "is_private": false
}
'

import requests

url = "https://api.markifact.com/v1/connections/auth-link"

payload = {
    "connection_type": "ga4",
    "redirect_url": "https://example.com/oauth/callback",
    "external_id": "customer_123",
    "is_private": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    connection_type: 'ga4',
    redirect_url: 'https://example.com/oauth/callback',
    external_id: 'customer_123',
    is_private: false
  })
};

fetch('https://api.markifact.com/v1/connections/auth-link', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.markifact.com/v1/connections/auth-link",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'connection_type' => 'ga4',
    'redirect_url' => 'https://example.com/oauth/callback',
    'external_id' => 'customer_123',
    'is_private' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.markifact.com/v1/connections/auth-link"

	payload := strings.NewReader("{\n  \"connection_type\": \"ga4\",\n  \"redirect_url\": \"https://example.com/oauth/callback\",\n  \"external_id\": \"customer_123\",\n  \"is_private\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.markifact.com/v1/connections/auth-link")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"connection_type\": \"ga4\",\n  \"redirect_url\": \"https://example.com/oauth/callback\",\n  \"external_id\": \"customer_123\",\n  \"is_private\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.markifact.com/v1/connections/auth-link")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"connection_type\": \"ga4\",\n  \"redirect_url\": \"https://example.com/oauth/callback\",\n  \"external_id\": \"customer_123\",\n  \"is_private\": false\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "url": "<string>",
  "expires_at": 123
}

{
  "detail": "<unknown>"
}

Creates an OAuth link for a user to connect an account. When the user completes the flow, Markifact stores the connection in your team workspace. By default, the resulting connection is shared with the workspace, so other team members can see and use it. Set is_private to true if the connection should only be visible and usable by the user who created the API key.

Endpoint

POST /v1/connections/auth-link

Request Body

Field	Type	Required	Description
`connection_type`	string	Yes	Supported connection type, such as `ga4`, `gads`, or `meta_ads`.
`redirect_url`	string	No	HTTPS URL to redirect the user to after the OAuth callback.
`external_id`	string	No	Your ID for the customer, store, workspace, or account. Max 255 characters.
`is_private`	boolean	No	Whether the created connection should be private to the API-key user. Defaults to `false`, meaning shared with the workspace so other team members can see and use it.

Best practices for `external_id`

external_id is how you tie a resulting connection back to a record in your own system. It is stored on the created connection and returned unchanged in both the connection responses and the redirect parameters.

Use a stable, unique ID from your system — your customer, workspace, store, or account ID. Avoid values that change over time so lookups stay reliable.
Keep it opaque. Don’t put PII or secrets in it (no emails, names, tokens). It is echoed back in the redirect URL query string, so it can land in browser history, referrer headers, and logs.
Use it to look connections up later with GET /v1/connections?external_id=... or GET /v1/connections/{external_id}?lookup_by=external_id, instead of storing Markifact connection IDs yourself.
Treat lookups as potentially returning multiple connections. external_id is not unique — a customer may reconnect or connect more than one account, so a single external_id can map to several connections.
Set it at creation time. It can only be provided when the link is created; it is not editable afterwards.

Example Request

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",
    "is_private": false
  }'

Response

{
  "id": "7b6a5c4d-0000-0000-0000-000000000000",
  "url": "https://app.markifact.com/connect?token=...",
  "expires_at": 1764086400000
}

Response Fields

Field	Type	Description
`id`	string	Auth link ID. Use this with the auth link status endpoint.
`url`	string	URL to send the user to.
`expires_at`	integer	Expiration timestamp in milliseconds.

Auth links expire 24 hours after creation, or as soon as a connection is successfully created — whichever comes first. Each link can be used to create one connection; generate a new link if it expires or has already been used.

Redirect URL Parameters

If you provide redirect_url, Markifact redirects the user’s browser back to that URL after the OAuth provider returns to Markifact. The redirect URL must use HTTPS. Markifact preserves any query parameters already on your URL and appends result metadata. Treat this browser redirect as a user-experience handoff, not as your only source of truth. For server-side confirmation, call the auth link status endpoint using the id returned when you created the link.

Success Redirect

When OAuth succeeds, Markifact stores the connection in your workspace, marks the auth link as connected, and redirects with:

status=success
connection_type=ga4
connection_id=1f2e3d4c-0000-0000-0000-000000000000
external_id=customer_123

Parameter	Description
`status`	`success` when the connection was created.
`connection_type`	The connection type originally requested, such as `ga4` or `gads`.
`connection_id`	The Markifact connection ID created by the completed OAuth flow. Use this with the connections API.
`external_id`	Your optional external ID, returned unchanged when provided.

Example final redirect:

https://example.com/oauth/callback?status=success&connection_type=ga4&connection_id=1f2e3d4c-0000-0000-0000-000000000000&external_id=customer_123

Error Redirect

When OAuth fails, is denied by the user, or cannot be completed, Markifact redirects with:

status=error
connection_type=ga4
external_id=customer_123
error=Authorization%20failed

Parameter	Description
`status`	`error` when the connection was not created.
`connection_type`	The connection type originally requested.
`external_id`	Your optional external ID, returned unchanged when provided.
`error`	A URL-encoded error message suitable for logging or showing a generic retry prompt.

Error redirects do not consume the auth link. The user can retry the same link until it expires.

Existing Query Parameters

Existing query parameters on your redirect_url are preserved. If your URL already contains one of Markifact’s parameter names, Markifact avoids overwriting it by adding a markifact_ prefix. For example, if you create a link with:

https://example.com/oauth/callback?status=started&session_id=abc

a successful redirect would look like:

https://example.com/oauth/callback?status=started&session_id=abc&markifact_status=success&connection_type=ga4&connection_id=1f2e3d4c-0000-0000-0000-000000000000&external_id=customer_123

Your redirect handler should read markifact_status when present, otherwise read status.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

connection_type

string

required

Example:

"ga4"

redirect_url

string<uri>

Example:

"https://example.com/oauth/callback"

external_id

string

Maximum string length: 255

Example:

"customer_123"

is_private

boolean

default:false

Whether the created connection should be private to the API-key user. Defaults to false, meaning shared with the workspace so other team members can see and use it.

Response

Auth link created.

string

required

url

string<uri>

required

expires_at

integer<int64>

required

Get Started

Connections

Credits

Logs

Create auth link

Endpoint

Request Body

Best practices for `external_id`

Example Request

Response

Response Fields

Redirect URL Parameters

Success Redirect

Error Redirect

Existing Query Parameters

Authorizations

Body

Response

​Endpoint

​Request Body

​Best practices for external_id

​Example Request

​Response

​Response Fields

​Redirect URL Parameters

​Success Redirect

​Error Redirect

​Existing Query Parameters

Authorizations

Body

Response

Endpoint

Request Body

Best practices for `external_id`

Example Request

Response

Response Fields

Redirect URL Parameters

Success Redirect

Error Redirect

Existing Query Parameters