Skip to main content
POST
Create connection
Creates a connection from credentials you already hold, without sending anyone through an OAuth flow. Use this when your systems already store the credentials, or when you connect through your own platform app. Markifact verifies the credentials with the provider before storing anything. A successful response means the connection is live and ready to use in nodes, agents, and MCP.

Endpoint

Which types this works for

Call List connection types and look at auth_methods: The same endpoint response lists each type’s credential_fields, which is exactly what belongs in credentials, and a docs_url pointing at a plain-markdown page that explains where each of those values comes from. Fetch that page when you need the steps for a channel.
Connecting through your own app on a channel where Markifact also has one requires the Team plan. Types that are manual only, such as Shopify, have no plan requirement beyond API access itself.

Request Body

Example Request

Response

Response Fields

Rotating credentials

Which connection a request updates depends on how the type derives its ID: Leave is_private out when replacing credentials. Omitting it keeps the connection’s current visibility.

Errors

Verification failures return the provider’s own reason in detail, so you can tell an expired refresh token from an app that lacks the right scope.
Nothing is stored when verification fails. Fix the credentials and post again.

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

A connection type whose auth_methods include "manual". See GET /v1/connections/types.

Example:

"gads"

name
string
required

Your label for the connection. For white-label types, posting the same type and name again replaces the stored credentials in place. Slack and Shopify are keyed on the workspace and store instead, and API-key types (Ahrefs, SEMrush, Adjust, DataForSEO, OpenAI Ads) always create a new connection.

Maximum string length: 100
Example:

"Acme Agency Google Ads"

credentials
object
required

Exactly the credential_fields the type lists. A missing or unrecognised field is rejected before any call to the provider.

Example:
is_private
boolean
default:false

Whether the 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. Omit it when replacing credentials on an existing connection and the current visibility is kept.

Response

Connection created and verified.

id
string | null
required

Public Markifact connection ID.

type
string
required

Connection type.

is_private
boolean
required
display_name
string | null
external_id
string | null
created_at
integer<int64> | null
updated_at
integer<int64> | null