Skip to main content
Each project prompt can choose which connected services the agent may use and which of their actions are allowed. These settings only narrow what the connection already allows. They never change workspace, organization or connection settings.

Available services and connected accounts

List connectors (GET /connectors, MCP list_connectors) shows what you can connect: GitHub, Notion, Google Drive, Getty Images and S3, plus YouTube, Instagram, TikTok, Facebook, X, Threads, LinkedIn, Reddit, Mastodon, Bluesky and Snapchat. Each option has a service id, an authentication method, an input_schema and setup availability. Check available before starting setup. List connections (GET /connections, MCP list_connections) shows the accounts you already connected. Every connection belongs to your API credential’s organization and workspace and is private to the member who connected it. Other members cannot list, read, use or delete it. Shared connection management can come later; the app’s existing shared connections keep their current behavior. Social connections use the same IDs in project prompts and Social posting. The two IDs have different purposes: Connection status is connected, unverified or needs_attention. verified_at is the time of its last check. Read GET /connections/{connection_id} (MCP get_connection) to inspect it. Google Drive and social status reads reconcile OAuth completion. A disconnected account returns 404. permission_options lists the action IDs a provider supports. capabilities says which are currently allowed for this account. Copy allowed permission_options[].id values into a project’s actions; these are permission groups, not raw tool names.

Choose connections for a prompt

Send connectors with POST /projects or POST /projects/{project_id}/messages (MCP: create_project, send_project_message):
  • id is a connection id from GET /connections. The project uses that exact account; Motion never picks another account of the same provider.
  • Choose at most one connection per provider. A project keeps the account it first used for a provider. To use a different account of that provider, start a new project.
  • actions is optional. It must be a subset of that connection’s permission_options ids that are currently allowed in capabilities. Omit it to keep the connection’s current actions.
  • Choosing connections requires motion:sessions:write and motion:connectors:read for your private connections in this organization workspace. Turning connectors off with [] only needs motion:sessions:write.

Actions by provider

Social actions never bypass posting approval. prepare creates a proposal. A private account’s creator must approve it in Socials while they are a workspace manager. Shared accounts require a workspace manager’s approval. Connection permissions enable all three social actions; each prompt can narrow them. Read a project to inspect its current connectors. null means no explicit selection, [] disables all connectors, and actions: null keeps the connection’s current allowed actions.

While the agent is working

Turning a connector off or narrowing actions while a turn is running takes effect at its next connector call. A newly enabled provider may become available on the next turn, when its tools connect. A turned-off connection, or an action outside the selection, is refused when the agent tries to use it. Every connector call also checks the live connection, workspace, organization and attached template/brand-kit restrictions. A template that prohibits a connection makes it unavailable even when the prompt explicitly selected it. If an admin later restricts an action, that restriction applies even when a prompt selected it.

Errors

A rejected request does not create a project or send a message.

Connect a service

Organization owners/admins and workspace members can connect tool services. Social account setup currently requires a workspace manager. Organization/workspace policies and product rollout restrictions still apply. The API never changes the credential’s workspace or shares a new connection. POST /connections (MCP connect_service) takes connector_id from the catalog and that option’s setup inputs. It needs motion:connectors:write and the organization member access reported by the catalog.

OAuth

The response contains status: "pending_authorization", an authorization_url, expires_at (when known) and connections_url. A person must open the link and approve access. Poll connections_url to find the saved connection’s UUID. Requesting a link or cancelling approval creates no connected account. Social setup accepts an optional name and request_id. Reuse the ID for retries; a completed request returns the saved connection. If an uncertain provider failure returns 409, start a fresh request ID. GitHub, Notion, Google Drive and the listed social platforms use their existing product authorization flows. Provider configuration, account access and rollout restrictions apply; check the catalog’s available field first.

Credentials

Getty Images accepts its API key and client secret:
S3 accepts AWS credentials and a bucket configuration:
S3 actions are files, downloads, uploads and deletes. The default is read-only files and downloads; read-only setup requires an existing nonempty read_test_key inside prefix. Optional credentials.session_token supports temporary AWS credentials. Motion verifies the requested AWS permissions before saving the connection. Bucket, region and prefix must pass the same constraints as the app; consult the catalog’s input_schema for field limits. Successful credential setup returns status: "connected" and the saved connection. Credentials are encrypted at rest and never included in list, read or project responses.

Disconnect

DELETE /connections/{connection_id} (MCP delete_connection) disconnects your private organization connection. Motion disconnects the account and revokes provider access where supported. Credential-based providers have no OAuth grant to revoke. Tool-service revocation failures retain the account for retry. Social disconnect disables local access immediately, even if the provider cannot confirm unlinking. Disconnecting a private social account cancels its pending posts that have not been submitted to the provider. Posts already submitted remain in reconciliation. Projects cannot use a deleted connection.