> ## 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. # Create auth link > Create a shareable OAuth link that connects an external account to your Markifact team. 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 ```http theme={"dark"} 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 ```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", "is_private": false }' ``` ## Response ```json theme={"dark"} { "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: ```text theme={"dark"} 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: ```text theme={"dark"} 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: ```text theme={"dark"} 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: ```text theme={"dark"} https://example.com/oauth/callback?status=started&session_id=abc ``` a successful redirect would look like: ```text theme={"dark"} 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`. ## OpenAPI ````yaml POST /v1/connections/auth-link openapi: 3.1.0 info: title: Markifact API version: 1.0.0 description: API for managing Markifact workspace connections. servers: - url: https://api.markifact.com security: - bearerAuth: [] paths: /v1/connections/auth-link: post: tags: - Connections summary: Create auth link description: >- Create a shareable OAuth link that connects an external account to your Markifact team. operationId: createAuthLink requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAuthLinkRequest' responses: '200': description: Auth link created. content: application/json: schema: $ref: '#/components/schemas/AuthLink' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CreateAuthLinkRequest: type: object properties: connection_type: type: string example: ga4 redirect_url: type: string format: uri example: https://example.com/oauth/callback external_id: type: string maxLength: 255 example: customer_123 is_private: type: boolean default: false description: >- 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. required: - connection_type AuthLink: type: object properties: id: type: string url: type: string format: uri expires_at: type: integer format: int64 required: - id - url - expires_at Error: type: object properties: detail: {} securitySchemes: bearerAuth: type: http scheme: bearer ````