The API reference moved here from eksis.io/developers.

Connect your customers' channels

Send a customer through the platform sign-in from your app, bring them back, and connect the accounts they pick.

Your customer never opens eksis. Your app starts a connect session, sends the customer to the platform's sign-in page, and connects the account they choose when they come back. The consent screen names eksis, because eksis is the app that holds the connection. For Instagram Login, Meta shows the app name "eksis - IG".

Connecting needs a key with the admin role, the same role that connects channels in the app.

Start a session

Send the platform and the address in your app the customer should come back to.

curl -X POST https://api.eksis.io/v1/connect \
  -H "Authorization: Bearer $EKSIS_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "via": "instagram_login",
    "returnUrl": "https://your-app.example/eksis/connected?customer=c_123"
  }'
  • returnUrl must be an https address. While you develop, http://localhost and http://127.0.0.1 work too. An address with a user name or password in it is refused.
  • Query parameters already in returnUrl are kept, so you can add your own reference to the customer, as customer=c_123 does above. Do not use the names eksis adds: session, status, platform, code, message, and hint.
  • Store sessionId next to the customer before you redirect. It is how you read the session later.
  • The session lasts 15 minutes (expiresAt).

Full reference: Start connecting a channel.

Send the customer to the sign-in page

Redirect the customer's browser to url. They sign in to the platform and approve the permissions eksis asks for.

Always send a returnUrl. Without one, the customer lands on the eksis account picker, which needs an eksis login they do not have.

Read the return

After sign-in, the platform sends the customer to eksis, and eksis sends them to your returnUrl with these query parameters added:

ParameterValue
platformThe platform of the session.
statusWhat happened. See below.
sessionThe session id. Present with ok and with the reasons below, not with denied or error.
code, message, hintOnly with status=error: the error code, a sentence for people, and sometimes what to do next.
statusMeaning
okThe customer signed in and accounts can be picked.
deniedThe customer declined on the platform's consent screen.
errorThe sign-in failed. Read code and message.
no_pagesFacebook sign-in, but the customer manages no Facebook Page.
ig_not_businessThe Instagram account is a Personal account. It has to be switched to Business or Creator in the Instagram app first.
no_channel, no_member, no_location, no_shopThe sign-in worked but there is nothing to connect on that platform, for example a Google account without a YouTube channel.

Show the customer a clear next step for every value other than ok, then let them start again.

See which accounts they can connect

Read the session to get the accounts the platform offered.

curl https://api.eksis.io/v1/connect/SESSION_ID \
  -H "Authorization: Bearer $EKSIS_ADMIN_KEY"

status is pending until the customer signs in, ready once accounts can be picked, connected after you connect them, and expired after 15 minutes.

For each candidate:

  • unavailableReason is set when the account cannot be picked, for example a personal Instagram account. Show the reason instead of a pick button.
  • connected is null for a new account, active when the account is already connected and healthy in this workspace, and reconnect when it is connected but needs to be picked again to repair it.

A session from another workspace answers 404 with connect.session_invalid, the same as one that does not exist. Reference: Read a connect session.

Connect the chosen accounts

Send back the platform, externalId, and pageId (when the candidate has one) of each account to connect. With one candidate you can skip the picker in your own app and send it straight away.

curl -X POST https://api.eksis.io/v1/connect/SESSION_ID/select \
  -H "Authorization: Bearer $EKSIS_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selections": [{ "platform": "instagram", "externalId": "17841400000000000" }]}'

connected counts new channels and reconnected counts channels that were repaired. Save each channels[].id with the customer: it is the channelId in posts, comments, conversations, and webhook events. Reference: Connect the chosen accounts.

Instagram: two ways to sign in

via: "instagram_login"Without via
Sign-in pageInstagramFacebook
Facebook Page neededNoYes, linked to the Instagram account
Accounts offeredThe one Instagram professional account that signs inThe customer's Facebook Pages and the Instagram accounts linked to them, each with pageId
Location tags on postsNot availableAvailable

Both need an Instagram Business or Creator account. For a customer who only uses Instagram, Instagram Login is the shorter path. via works only with platform: "instagram".

Channel slots

Each new account takes one channel slot. When the workspace is full, POST /v1/connect and select answer 402 with plan.limit_reached. Picking an account marked reconnect repairs it without taking a new slot, so a repair works even when the workspace is full. See Workspaces and limits.

Platforms you cannot connect through the API

Bluesky connects with a handle and an app password, and DEV Community with an API key. POST /v1/connect refuses both with connect.needs_credentials. Telegram connects by adding the eksis bot to a chat. Connect these in the eksis app.

Repair a broken connection

A channel stops working when the platform no longer accepts the permission eksis holds, for example because the customer removed eksis from the account's connected apps. A short outage on the platform's side does not count: eksis retries instead. When the connection does break, eksis holds the posts scheduled to the channel and sends channel.unhealthy to your webhook endpoint.

Notice it

Subscribe to channel.unhealthy. Its data.channel.id tells you which customer to contact, and data.reason says why the connection dropped. See Channel lost its connection.

Start a session for the same platform

Ask the customer to sign in again, and start a session the same way they connected the first time, with the same via if they used Instagram Login.

Pick the account again

The account appears among the candidates with connected: "reconnect". Send it to select. The channel keeps its id, reconnected is 1, and the held posts are released once the channel is healthy.

From an AI assistant

The MCP server has the same three steps as tools: start_channel_connect, get_channel_connect, and finish_channel_connect.

On this page