Skip to main content
POST
/
v1
/
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
}
'
{
  "id": "<string>",
  "url": "<string>",
  "expires_at": 123
}

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.

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

FieldTypeRequiredDescription
connection_typestringYesSupported connection type, such as ga4, gads, or meta_ads.
redirect_urlstringNoHTTPS URL to redirect the user to after the OAuth callback.
external_idstringNoYour ID for the customer, store, workspace, or account. Max 255 characters.
is_privatebooleanNoWhether 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

FieldTypeDescription
idstringAuth link ID. Use this with the auth link status endpoint.
urlstringURL to send the user to.
expires_atintegerExpiration 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
ParameterDescription
statussuccess when the connection was created.
connection_typeThe connection type originally requested, such as ga4 or gads.
connection_idThe Markifact connection ID created by the completed OAuth flow. Use this with the connections API.
external_idYour 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
ParameterDescription
statuserror when the connection was not created.
connection_typeThe connection type originally requested.
external_idYour optional external ID, returned unchanged when provided.
errorA 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.

​
id
string
required
​
url
string<uri>
required
​
expires_at
integer<int64>
required