> ## Documentation Index
> Fetch the complete documentation index at: https://docs.motion.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a service

> Connect a service using its catalog ID. OAuth returns an approval link; credentials are verified before saving. New connections are private to their creator inside the organization. Social account setup requires a workspace manager.



## OpenAPI

````yaml /openapi.json post /connections
openapi: 3.1.0
info:
  title: Motion
  version: 1.1.0
  description: >-
    Create Motion projects from prompts, read authored generations and outputs,
    and explicitly request renders or editor exports. Use reusable templates and
    brand kits. Credentials remain bound to current workspace access and
    permissions. Legacy single-video endpoints are deprecated.
servers:
  - url: https://api.motion.so/api/motion
security:
  - MotionApiKey: []
tags:
  - name: Projects
  - name: Project results
  - name: Project exports
  - name: Templates
  - name: Brand kits
  - name: Media library
  - name: Automations
  - name: Social posting
  - name: API information
  - name: Deprecated endpoints
    description: >-
      Older single-video routes remain callable for existing clients. Use the
      project API for new integrations; no removal date is scheduled.
  - name: Connectors
    description: Connect services and control the actions a project may use.
paths:
  /connections:
    post:
      tags:
        - Connectors
      summary: Connect a service
      description: >-
        Connect a service using its catalog ID. OAuth returns an approval link;
        credentials are verified before saving. New connections are private to
        their creator inside the organization. Social account setup requires a
        workspace manager.
      operationId: ConnectService
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MotionConnectServiceRequest'
            examples:
              oauth:
                summary: Connect an OAuth service
                value:
                  connector_id: google-drive
              getty:
                summary: Connect Getty with credentials
                value:
                  connector_id: getty
                  credentials:
                    api_key: YOUR_GETTY_API_KEY
                    client_secret: YOUR_GETTY_CLIENT_SECRET
              s3:
                summary: Read-only S3 access
                value:
                  connector_id: s3
                  credentials:
                    access_key_id: AKIAEXAMPLE00000000
                    secret_access_key: YOUR_AWS_SECRET_ACCESS_KEY
                  config:
                    bucket: acme-media
                    region: us-east-1
                    prefix: motion/
                    read_test_key: motion/existing-video.mp4
                  actions:
                    - files
                    - downloads
      responses:
        '201':
          description: Connection setup started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotionConnectServiceResponse'
              example:
                connector_id: google-drive
                scope: organization
                status: pending_authorization
                authorization_url: https://connect.nango.dev/?connect_session_token=EXAMPLE
                expires_at: '2026-11-17T20:30:00Z'
                connections_url: /api/motion/connections?connector_id=google-drive
                visibility: private
        '400':
          description: Invalid provider inputs or credential verification failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or revoked credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Required scope or current account access denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Private organization connection not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Provider setup is not configured or temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - MotionApiKey: []
        - MotionOAuth:
            - motion:connectors:write
components:
  schemas:
    MotionConnectServiceRequest:
      oneOf:
        - type: object
          properties:
            connector_id:
              type: string
              enum:
                - github
                - notion
                - google-drive
          required:
            - connector_id
          additionalProperties: false
          title: OAuth service
        - type: object
          properties:
            connector_id:
              type: string
              enum:
                - tiktok
                - youtube
                - instagram
                - facebook
                - x
                - threads
                - linkedin
                - reddit
                - mastodon
                - bluesky
                - snapchat
            name:
              description: Optional account label.
              type: string
              minLength: 1
              maxLength: 120
            request_id:
              description: Reuse this ID when retrying the same connection request.
              type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          required:
            - connector_id
          additionalProperties: false
          title: Social account
        - type: object
          properties:
            connector_id:
              type: string
              const: getty
            credentials:
              type: object
              properties:
                api_key:
                  type: string
                  minLength: 1
                  maxLength: 8192
                  description: >-
                    Provider credential. Encrypted at rest and never returned by
                    the API.
                  writeOnly: true
                client_secret:
                  type: string
                  minLength: 1
                  maxLength: 8192
                  description: >-
                    Provider credential. Encrypted at rest and never returned by
                    the API.
                  writeOnly: true
              required:
                - api_key
                - client_secret
              additionalProperties: false
              description: >-
                Getty application credentials, verified before saving and never
                returned.
          required:
            - connector_id
            - credentials
          additionalProperties: false
          title: Getty credentials
        - type: object
          properties:
            connector_id:
              type: string
              const: s3
            credentials:
              type: object
              properties:
                access_key_id:
                  type: string
                  minLength: 16
                  maxLength: 128
                  pattern: ^[A-Za-z0-9]+$
                  description: >-
                    AWS access key ID used to verify the requested bucket
                    permissions.
                  writeOnly: true
                secret_access_key:
                  type: string
                  minLength: 16
                  maxLength: 256
                  description: AWS secret access key, encrypted at rest and never returned.
                  writeOnly: true
                session_token:
                  type: string
                  minLength: 1
                  maxLength: 8192
                  description: >-
                    Provider credential. Encrypted at rest and never returned by
                    the API.
                  writeOnly: true
              required:
                - access_key_id
                - secret_access_key
              additionalProperties: false
              description: AWS credentials, optionally including a temporary session token.
            config:
              type: object
              properties:
                bucket:
                  type: string
                  minLength: 3
                  maxLength: 63
                  pattern: ^[a-z0-9][a-z0-9.-]*[a-z0-9]$
                  description: S3 bucket name. No IP addresses or consecutive dots.
                region:
                  type: string
                  maxLength: 40
                  pattern: ^[a-z]{2}(?:-[a-z]+)+-\d+$
                  description: AWS region, for example us-east-1.
                prefix:
                  default: ''
                  description: >-
                    Literal object prefix; no wildcard, control characters, dot
                    or parent path segments.
                  type: string
                  maxLength: 900
                read_test_key:
                  description: >-
                    Existing nonempty object key inside prefix, required to
                    verify read-only access.
                  type: string
                  minLength: 1
                  maxLength: 1024
              required:
                - bucket
                - region
              additionalProperties: false
              description: >-
                The S3 bucket, region and literal object prefix this connection
                may access.
            actions:
              default:
                - files
                - downloads
              description: >-
                AWS actions to verify. Defaults to read-only files and
                downloads. Read-only setup requires an existing nonempty
                read_test_key inside the prefix.
              minItems: 1
              maxItems: 4
              type: array
              items:
                type: string
                enum:
                  - files
                  - downloads
                  - uploads
                  - deletes
          required:
            - connector_id
            - credentials
            - config
          additionalProperties: false
          title: S3 credentials
    MotionConnectServiceResponse:
      anyOf:
        - type: object
          properties:
            connector_id:
              type: string
              enum:
                - github
                - notion
                - google-drive
                - getty
                - s3
                - tiktok
                - youtube
                - instagram
                - facebook
                - x
                - threads
                - linkedin
                - reddit
                - mastodon
                - bluesky
                - snapchat
                - figma
                - dropbox
                - slack
                - x-account
              description: Service ID; the connection id identifies a saved account.
            scope:
              type: string
              const: organization
              description: >-
                Connection belongs to the credential’s organization and
                workspace.
            visibility:
              type: string
              const: private
            status:
              type: string
              const: pending_authorization
            authorization_url:
              type: string
              format: uri
              description: >-
                Provider authorization page for a person to approve; this
                response is not a connected account.
            expires_at:
              type:
                - string
                - 'null'
            connections_url:
              type: string
              description: >-
                Poll this API path after approval to discover the saved
                connection UUID.
          required:
            - connector_id
            - scope
            - visibility
            - status
            - authorization_url
            - expires_at
            - connections_url
          additionalProperties: false
          title: Pending authorization
        - type: object
          properties:
            connector_id:
              type: string
              enum:
                - github
                - notion
                - google-drive
                - getty
                - s3
                - tiktok
                - youtube
                - instagram
                - facebook
                - x
                - threads
                - linkedin
                - reddit
                - mastodon
                - bluesky
                - snapchat
                - figma
                - dropbox
                - slack
                - x-account
              description: Service ID; the connection id identifies a saved account.
            scope:
              type: string
              const: organization
              description: >-
                Connection belongs to the credential’s organization and
                workspace.
            visibility:
              type: string
              const: private
            status:
              type: string
              const: connected
            connection:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  pattern: >-
                    ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                connector_id:
                  type: string
                  enum:
                    - github
                    - notion
                    - google-drive
                    - getty
                    - s3
                    - tiktok
                    - youtube
                    - instagram
                    - facebook
                    - x
                    - threads
                    - linkedin
                    - reddit
                    - mastodon
                    - bluesky
                    - snapchat
                    - figma
                    - dropbox
                    - slack
                    - x-account
                  description: Service ID; the connection id identifies a saved account.
                scope:
                  type: string
                  const: organization
                  description: >-
                    Connection belongs to the credential’s organization and
                    workspace.
                visibility:
                  type: string
                  const: private
                organization_id:
                  type: string
                workspace_id:
                  type: string
                  format: uuid
                  pattern: >-
                    ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                name:
                  type: string
                  description: Connected account display name.
                status:
                  type: string
                  enum:
                    - connected
                    - unverified
                    - needs_attention
                  description: >-
                    Latest recorded verification: connected passed, unverified
                    has not been checked, needs_attention failed. Managed OAuth
                    status reconciles with the provider broker.
                can_use:
                  type: boolean
                  description: >-
                    Account passed verification and this actor may use it;
                    project template/kit and organization restrictions are
                    checked during execution.
                capabilities:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    type: boolean
                permission_options:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      label:
                        type: string
                      write:
                        type: boolean
                    required:
                      - id
                      - label
                      - write
                    additionalProperties: false
                verified_at:
                  description: >-
                    Time of the last provider verification, or null if not yet
                    checked.
                  type:
                    - string
                    - 'null'
                created_at:
                  type: string
                updated_at:
                  type: string
                error:
                  type:
                    - string
                    - 'null'
              required:
                - id
                - connector_id
                - scope
                - visibility
                - organization_id
                - workspace_id
                - name
                - status
                - can_use
                - capabilities
                - permission_options
                - verified_at
                - created_at
                - updated_at
                - error
              additionalProperties: false
              description: >-
                The verified creator-private account saved in this organization
                workspace.
          required:
            - connector_id
            - scope
            - visibility
            - status
            - connection
          additionalProperties: false
          title: Connected account
    ErrorResponse:
      type: object
      description: >-
        Error bodies are JSON. Check the HTTP status first. Permission and
        validation errors use error; service errors may use detail. Optional
        fields explain how to correct the request.
      anyOf:
        - required:
            - error
        - required:
            - detail
      properties:
        error:
          type: string
          description: Error code or readable explanation.
        detail:
          type: string
          description: Readable explanation from the service.
        message:
          type: string
          description: Readable explanation accompanying an error code.
        error_description:
          type: string
          description: Authentication or permission explanation.
        required_scope:
          type: string
          description: Permission required by this operation.
        details:
          type: array
          description: Invalid request fields. Each issue includes a path and message.
          items:
            type: object
            properties:
              code:
                type: string
              path:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: integer
              message:
                type: string
        issues:
          type: array
          description: Service validation issues.
          items:
            type: object
  securitySchemes:
    MotionApiKey:
      type: http
      scheme: bearer
      description: >-
        A Motion API key. Access is limited to its stored organization,
        workspace, scopes and the creator’s current permissions.
    MotionOAuth:
      type: oauth2
      description: >-
        OAuth REST tokens use the full MCP audience, https://mcp.motion.so/mcp.
        Reauthorize existing connections to add scopes. Current workspace roles
        and resource permissions still apply.
      flows:
        authorizationCode:
          authorizationUrl: https://mcp.motion.so/oauth/authorize
          tokenUrl: https://mcp.motion.so/oauth/token
          scopes:
            motion:automations:read: Read automation definitions, capabilities, runs, and analytics.
            motion:automations:write: Create, edit, delete, invoke, and retry automations.
            motion:connectors:read: >-
              Read available services, your private organization connections and
              allowed actions without secrets.
            motion:connectors:write: >-
              Connect and disconnect your private accounts inside the credential
              organization workspace.
            motion:templates:read: Read and preview accessible templates.
            motion:templates:write: Create, edit, share, and archive prompt templates.
            motion:sessions:read: Read permitted chats, job status and saved exports.
            motion:sessions:write: >-
              Create and steer Motion projects using organization workspace
              credits.
            motion:assets:read: Find and read permitted media library assets.
            motion:brand-kits:read: Read permitted brand kits.
            motion:brand-kits:write: Create and edit brand kits within current app permissions.
            motion:social:read: Read authorized social accounts and posts.
            motion:social:write: >-
              Draft, submit, approve and cancel posts within current app
              permissions.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.