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"
}'returnUrlmust be anhttpsaddress. While you develop,http://localhostandhttp://127.0.0.1work too. An address with a user name or password in it is refused.- Query parameters already in
returnUrlare kept, so you can add your own reference to the customer, ascustomer=c_123does above. Do not use the names eksis adds:session,status,platform,code,message, andhint. - Store
sessionIdnext 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:
| Parameter | Value |
|---|---|
platform | The platform of the session. |
status | What happened. See below. |
session | The session id. Present with ok and with the reasons below, not with denied or error. |
code, message, hint | Only with status=error: the error code, a sentence for people, and sometimes what to do next. |
status | Meaning |
|---|---|
ok | The customer signed in and accounts can be picked. |
denied | The customer declined on the platform's consent screen. |
error | The sign-in failed. Read code and message. |
no_pages | Facebook sign-in, but the customer manages no Facebook Page. |
ig_not_business | The 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_shop | The 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:
unavailableReasonis set when the account cannot be picked, for example a personal Instagram account. Show the reason instead of a pick button.connectedisnullfor a new account,activewhen the account is already connected and healthy in this workspace, andreconnectwhen 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 page | ||
| Facebook Page needed | No | Yes, linked to the Instagram account |
| Accounts offered | The one Instagram professional account that signs in | The customer's Facebook Pages and the Instagram accounts linked to them, each with pageId |
| Location tags on posts | Not available | Available |
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.