---
topic: integrations
connector: "Not yet: use the HTTP calls below with the app's token"
api: "POST https://ship.embarko.ai/api/apps/{app-name}/integrations"
needs_human: Nothing. Users build their own flows in the panel.
requires: [claim]
---

[← Guide home](https://embarko.ai/docs)

# Connect other apps

**On this page:** Over HTTP, Examples, Limits, Errors, What to tell the person

> Plain words unless the person is a developer. Never invent a link, name or code. [Rules](https://embarko.ai/docs/prerequisites) Needs first: [claim](https://embarko.ai/docs/claim) (over HTTP only).

Integrations gives the app an embedded integrations panel (viaSocket's prebuilt embed). You turn it on and the app gets three env vars: INTEGRATIONS_ORG_ID, INTEGRATIONS_PROJECT_ID and INTEGRATIONS_SECRET. Then you build the panel by following viaSocket's skill, using those three where it reads VIASOCKET_ORG_ID, VIASOCKET_PROJECT_ID and VIASOCKET_EMBED_SECRET. You never ask the person for them.

**Connector:** Not yet: use the HTTP calls below with the app's token

**Done when:** Integrations is on, the app reads the three env vars, and each line of the viaSocket skill's "Finished when" list is reported.

**Over HTTP**

1. Turn it on: POST https://ship.embarko.ai/api/apps/{app-name}/integrations with {"apply": true}. Safe to repeat (alreadyEnabled: true). "apply": true pushes the env vars to the running app; without it they arrive on the next deploy. They live on Embarko, not in the local .env.
2. A 409 integrations_disabled_for_workspace means the workspace has Integrations off. Embarko has already emailed the workspace Owners naming this app, with a link to turn it on under Settings. Tell the person, and do not retry until they say it is on.
3. Download https://flow.viasocket.com/documentation/skill.md to .claude/skills/viasocket-integrations/SKILL.md inside the app folder and follow it. Use its prebuilt embed UI route. Add viasocket-apps to the app's dependencies; Embarko's build installs it.
4. Do not ask the person for the org ID, project ID or secret: Embarko set them. Where viaSocket's skill reads VIASOCKET_ORG_ID, VIASOCKET_PROJECT_ID and VIASOCKET_EMBED_SECRET, use INTEGRATIONS_ORG_ID, INTEGRATIONS_PROJECT_ID and INTEGRATIONS_SECRET instead, in that order. Never hardcode them; never send the secret to the browser. To the person, say "Integrations", not viaSocket.
5. If your sandbox blocks running the skill's downloaded check script, skip the proof step and say so.
6. Decide who supplies each value and who picks the action, then report each line of the viaSocket skill's "Finished when" list.

**Example: Turn it on**

body.json:

```json
{"apply":true}
```

```bash
curl -sS -X POST 'https://ship.embarko.ai/api/apps/my-app/integrations' --oauth2-bearer $DEPLOY_TOKEN -H 'Content-Type: application/json' --data @body.json
```

Reply 202:

```json
{"enabled":true,"envVars":["INTEGRATIONS_ORG_ID","INTEGRATIONS_PROJECT_ID","INTEGRATIONS_SECRET"],"applied":true}
```

**Limits**

- The env vars reach the running app on the next deploy, or at once with "apply": true.
- If the app already sets any of the three itself, turning it on is refused rather than overwriting them.
- Static sites cannot use it: nothing runs that could read the env vars.
- Needs a kept app: a temporary one has no workspace.
- The workspace switch comes first: only a workspace Owner can turn Integrations on for the workspace (dashboard, Settings). Until then no app in it can turn it on.
- Moving the app to another workspace turns Integrations off. Turn it on again there.

**Errors**

| Code | Status | Retry | What to do |
| --- | --- | --- | --- |
| `integrations_not_configured` | 503 | No | Integrations is not available on this environment. Tell the person; do not retry. |
| `integrations_disabled_for_workspace` | 409 | Only after the person says it is on | The workspace has Integrations off. Embarko emailed the workspace Owners about this app with a link to turn it on. Tell the person; do not retry on your own. |
| `env_var_conflict` | 409 | No | The app already sets one of the three env vars itself. Remove it (see env-vars), then turn it on again. |
| `app_not_claimed` | 409 | No | The app is still temporary. Claim it first (see claim), then turn Integrations on. |
| `not_supported_for_static` | 409 | No | A static site has no server to read the env vars. Deploy it as a server app under a new name. |
| `email_required` | 409 | No | The workspace owner has no email on their account. Tell the person to add one, then retry. |
| `integrations_unavailable` | 502 | Yes, later | The integrations engine did not answer. Retry with a backoff. |
| `permission_denied` | 403 | No | The token's person cannot see this app. Relay the message: a workspace Owner or Admin has to give them access. |

**What to tell the person**

- offer: "I can add an integrations panel to your app, where your users connect Slack, Sheets and other tools and build their own flows."
- done: "Done: your app has an integrations panel. Your users connect tools and build flows there; nothing in the app changes when they do."

**Next:** Turn it on, then follow viaSocket's skill with the three env vars Embarko already set.

**Related:** [env-vars](https://embarko.ai/docs/env-vars) · [deploy](https://embarko.ai/docs/deploy) · [static-sites](https://embarko.ai/docs/static-sites)

---

[Guide home](https://embarko.ai/docs) · JSON: add .json