---
topic: move
connector: "Not in the connector yet: use the HTTP call with a \"Just me\" token, or send the person to the app's Settings"
api: "POST https://ship.embarko.ai/api/apps/{app-name}/move"
needs_human: "A yes, and a \"Just me\" token from the workspace the app should go to if you do not have one."
requires: [claim]
---

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

# Move an app to another workspace

**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).

You move the app with one call: POST https://ship.embarko.ai/api/apps/{app-name}/move with a "Just me" token from the workspace it should go to. Only the owner changes: same link, same appId, same settings, nothing redeployed. Changing the token alone never moves an app, because a "Just me" token reaches the app wherever it is.

**Connector:** Not in the connector yet: use the HTTP call with a "Just me" token, or send the person to the app's Settings

**Done when:** The move call answered moved: true, and GET https://ship.embarko.ai/api/apps/{app-name} shows the new workspace.

**Over HTTP**

1. Confirm with the person, naming the app and the workspace it goes to.
2. Use a "Just me" token from that workspace. If you do not have one, ask for it: the token email sends one per workspace, and they paste the one for the target workspace.
3. POST https://ship.embarko.ai/api/apps/{app-name}/move with that token and no body. The app goes to the token's workspace.
4. If you know the target workspace id, send {"workspaceId": "..."} instead, with any "Just me" token of theirs.
5. Read to.name in the reply and tell the person. Keep deploying as before: same name, same appId.

**Example: Move to the token's workspace**

```bash
curl -sS -X POST 'https://ship.embarko.ai/api/apps/my-app/move' --oauth2-bearer "$DEPLOY_TOKEN"
```

Reply 200:

```json
{"projectId":"cmh1q2w3e0001abcdmyapp","name":"my-app","appUrl":"https://my-app.embarko.app","moved":true,"from":{"id":"company_old","name":"Rita"},"to":{"id":"company_new","name":"Acme"},"redeployNeeded":false,"integrationsTurnedOff":true,"footerResync":false}
```

**Example: Which workspace it is in**

```bash
curl -sS 'https://ship.embarko.ai/api/apps/my-app' --oauth2-bearer "$DEPLOY_TOKEN"
```

Reply 200:

```json
{"id":"cmh1q2w3e0001abcdmyapp","name":"my-app","workspace":{"id":"company_new","name":"Acme"}}
```

**Limits**

- The person must be in both workspaces, with Full access to the app and the right to add apps in the target.
- Moving turns Integrations off. Turn it on again in the new workspace if the app used it (see integrations).
- Afterwards a "Whole workspace" token of the old workspace gets 409 app_moved for this app.
- No HTTP access, or no token: the person can do it in the dashboard, in the app's Settings → Move to another workspace.

**Errors**

| Code | Status | Retry | What to do |
| --- | --- | --- | --- |
| `same_workspace` | 400 | No | The app is already in this token's workspace. Ask for a "Just me" token from the workspace it should move to. Do not redeploy under a new name. |
| `user_token_required` | 403 | No | A "Whole workspace" token cannot move apps. Ask for a "Just me" token from the target workspace. |
| `no_access` | 403 | No | The person cannot move apps out of this workspace, or cannot add apps in the target. Tell them; an Owner or Admin can change that. |
| `deploy_in_progress / rename_in_progress` | 409 | Later | Wait for it to finish, then move. |
| `move_conflict` | 409 | Once | The app changed during the move. Retry once. |
| `permission_denied` | 403 | No | The person who made this token is not allowed to do this. The reply names the permission and their access to the app (or their role). Nothing changed. Tell the person (say_to_user.no_permission); do not try another way round it. |

**What to tell the person**

- confirm: "I'll move {app} to the {workspace} workspace. The link stays the same and nothing goes offline. Go ahead?"
- ask_token: "Paste a token from the {workspace} workspace and I'll move the app there."
- done: "Done: {app} is now in the {workspace} workspace. Same link: {link}."

**Next:** Ask first, then move.

**Related:** [claim](https://embarko.ai/docs/claim) · [team](https://embarko.ai/docs/team)

---

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