Integration Setup Sessions

Integration setup sessions orchestrate configuring every provider required by an integration instance.

Integration Setup Sessions object

Attributes

object

String

status

Enum

url

String

name

StringNullable

description

StringNullable

metadata

ObjectNullable

A key-value map

configuration

ObjectNullable

A key-value map

redirect_url

StringNullable

integration_id

String

integration_instance_id

String

integration_instance

Object

steps

Object

created_at

Date

updated_at

Date

expires_at

Date

{
  "object": "integration.setup_session",
  "status": "pending",
  "metadata": {},
  "configuration": {},
  "integration_instance": {
    "object": "integration.instance",
    "status": "draft",
    "metadata": {},
    "implementation": {
      "type": "magic_mcp_server"
    },
    "providers": [
      {
        "object": "integration.instance.provider",
        "status": "active",
        "metadata": {},
        "tool_filter": {
          "type": "allow_all"
        },
        "provider": {
          "object": "provider#preview",
          "id": "pro_5gHjKlMnPqRsTuVw",
          "name": "GitHub",
          "description": "Connect to GitHub repositories, issues, and pull requests",
          "slug": "github",
          "created_at": "2025-09-15T10:30:00.000Z",
          "updated_at": "2026-01-10T14:45:00.000Z"
        },
        "integration_provider": {
          "object": "integration.provider#snapshot",
          "provider_version": {
            "object": "integration.provider.version"
          },
          "status": "active",
          "metadata": {},
          "tool_filter": {
            "type": "allow_all"
          },
          "provider": {
            "object": "provider#preview",
            "id": "pro_5gHjKlMnPqRsTuVw",
            "name": "GitHub",
            "description": "Connect to GitHub repositories, issues, and pull requests",
            "slug": "github",
            "created_at": "2025-09-15T10:30:00.000Z",
            "updated_at": "2026-01-10T14:45:00.000Z"
          },
          "deployment": {
            "object": "provider.deployment#preview",
            "id": "pde_1aBcDeFgHjKlMnPq",
            "name": "Production",
            "description": "Production deployment",
            "metadata": {},
            "provider_id": "pro_5gHjKlMnPqRsTuVw",
            "created_at": "2025-09-15T10:30:00.000Z",
            "updated_at": "2026-01-10T14:45:00.000Z"
          },
          "auth_method": {
            "object": "provider.capabilities.auth_method",
            "id": "pam_2mNpQrStUvWxYzAb",
            "type": "oauth",
            "key": "oauth2",
            "name": "OAuth 2.0",
            "description": "Authenticate using OAuth 2.0",
            "capabilities": {},
            "input_schema": {
              "type": "json_schema",
              "schema": {}
            },
            "output_schema": {
              "type": "json_schema",
              "schema": {}
            },
            "scopes": [
              {
                "object": "provider.capabilities.auth_method.scope",
                "id": "pams_8tUvWxYzAbCdEfGh",
                "scope": "repo",
                "name": "Repository Access",
                "description": "Full control of private repositories"
              },
              {
                "object": "provider.capabilities.auth_method.scope",
                "id": "pams_8tUvWxYzAbCdEfGh",
                "scope": "repo",
                "name": "Repository Access",
                "description": "Full control of private repositories"
              }
            ],
            "provider_id": "pro_5gHjKlMnPqRsTuVw",
            "provider_specification_id": "psp_9gHjKlMnPqRsTuVw",
            "created_at": "2025-09-15T10:30:00.000Z",
            "updated_at": "2026-01-10T14:45:00.000Z"
          },
          "auth_credentials": {
            "object": "provider.auth_credentials",
            "id": "par_4sTuVwXyZaBcDeFg",
            "type": "oauth",
            "status": "active",
            "is_default": true,
            "is_managed": true,
            "name": "GitHub OAuth",
            "description": "OAuth credentials for GitHub API",
            "metadata": {},
            "provider_id": "pro_5gHjKlMnPqRsTuVw",
            "created_at": "2025-09-15T10:30:00.000Z",
            "updated_at": "2026-01-10T14:45:00.000Z"
          },
          "config": {
            "object": "provider.config#preview",
            "id": "pcf_7dEfGhJkLmNpQrSt",
            "name": "Production Config",
            "description": "Configuration for production environment",
            "metadata": {},
            "provider_id": "pro_5gHjKlMnPqRsTuVw",
            "created_at": "2025-09-15T10:30:00.000Z",
            "updated_at": "2026-01-10T14:45:00.000Z"
          }
        },
        "config": {
          "object": "provider.config#preview",
          "id": "pcf_7dEfGhJkLmNpQrSt",
          "name": "Production Config",
          "description": "Configuration for production environment",
          "metadata": {},
          "provider_id": "pro_5gHjKlMnPqRsTuVw",
          "created_at": "2025-09-15T10:30:00.000Z",
          "updated_at": "2026-01-10T14:45:00.000Z"
        },
        "auth_config": {
          "object": "provider.auth_config#preview",
          "id": "pcf_7dEfGhJkLmNpQrSt",
          "name": "Production Config",
          "description": "Configuration for production environment",
          "metadata": {},
          "provider_id": "pro_5gHjKlMnPqRsTuVw",
          "created_at": "2025-09-15T10:30:00.000Z",
          "updated_at": "2026-01-10T14:45:00.000Z"
        }
      },
      {
        "object": "integration.instance.provider",
        "status": "active",
        "metadata": {},
        "tool_filter": {
          "type": "allow_all"
        },
        "provider": {
          "object": "provider#preview",
          "id": "pro_5gHjKlMnPqRsTuVw",
          "name": "GitHub",
          "description": "Connect to GitHub repositories, issues, and pull requests",
          "slug": "github",
          "created_at": "2025-09-15T10:30:00.000Z",
          "updated_at": "2026-01-10T14:45:00.000Z"
        },
        "integration_provider": {
          "object": "integration.provider#snapshot",
          "provider_version": {
            "object": "integration.provider.version"
          },
          "status": "active",
          "metadata": {},
          "tool_filter": {
            "type": "allow_all"
          },
          "provider": {
            "object": "provider#preview",
            "id": "pro_5gHjKlMnPqRsTuVw",
            "name": "GitHub",
            "description": "Connect to GitHub repositories, issues, and pull requests",
            "slug": "github",
            "created_at": "2025-09-15T10:30:00.000Z",
            "updated_at": "2026-01-10T14:45:00.000Z"
          },
          "deployment": {
            "object": "provider.deployment#preview",
            "id": "pde_1aBcDeFgHjKlMnPq",
            "name": "Production",
            "description": "Production deployment",
            "metadata": {},
            "provider_id": "pro_5gHjKlMnPqRsTuVw",
            "created_at": "2025-09-15T10:30:00.000Z",
            "updated_at": "2026-01-10T14:45:00.000Z"
          },
          "auth_method": {
            "object": "provider.capabilities.auth_method",
            "id": "pam_2mNpQrStUvWxYzAb",
            "type": "oauth",
            "key": "oauth2",
            "name": "OAuth 2.0",
            "description": "Authenticate using OAuth 2.0",
            "capabilities": {},
            "input_schema": {
              "type": "json_schema",
              "schema": {}
            },
            "output_schema": {
              "type": "json_schema",
              "schema": {}
            },
            "scopes": [
              {
                "object": "provider.capabilities.auth_method.scope",
                "id": "pams_8tUvWxYzAbCdEfGh",
                "scope": "repo",
                "name": "Repository Access",
                "description": "Full control of private repositories"
              },
              {
                "object": "provider.capabilities.auth_method.scope",
                "id": "pams_8tUvWxYzAbCdEfGh",
                "scope": "repo",
                "name": "Repository Access",
                "description": "Full control of private repositories"
              }
            ],
            "provider_id": "pro_5gHjKlMnPqRsTuVw",
            "provider_specification_id": "psp_9gHjKlMnPqRsTuVw",
            "created_at": "2025-09-15T10:30:00.000Z",
            "updated_at": "2026-01-10T14:45:00.000Z"
          },
          "auth_credentials": {
            "object": "provider.auth_credentials",
            "id": "par_4sTuVwXyZaBcDeFg",
            "type": "oauth",
            "status": "active",
            "is_default": true,
            "is_managed": true,
            "name": "GitHub OAuth",
            "description": "OAuth credentials for GitHub API",
            "metadata": {},
            "provider_id": "pro_5gHjKlMnPqRsTuVw",
            "created_at": "2025-09-15T10:30:00.000Z",
            "updated_at": "2026-01-10T14:45:00.000Z"
          },
          "config": {
            "object": "provider.config#preview",
            "id": "pcf_7dEfGhJkLmNpQrSt",
            "name": "Production Config",
            "description": "Configuration for production environment",
            "metadata": {},
            "provider_id": "pro_5gHjKlMnPqRsTuVw",
            "created_at": "2025-09-15T10:30:00.000Z",
            "updated_at": "2026-01-10T14:45:00.000Z"
          }
        },
        "config": {
          "object": "provider.config#preview",
          "id": "pcf_7dEfGhJkLmNpQrSt",
          "name": "Production Config",
          "description": "Configuration for production environment",
          "metadata": {},
          "provider_id": "pro_5gHjKlMnPqRsTuVw",
          "created_at": "2025-09-15T10:30:00.000Z",
          "updated_at": "2026-01-10T14:45:00.000Z"
        },
        "auth_config": {
          "object": "provider.auth_config#preview",
          "id": "pcf_7dEfGhJkLmNpQrSt",
          "name": "Production Config",
          "description": "Configuration for production environment",
          "metadata": {},
          "provider_id": "pro_5gHjKlMnPqRsTuVw",
          "created_at": "2025-09-15T10:30:00.000Z",
          "updated_at": "2026-01-10T14:45:00.000Z"
        }
      }
    ]
  },
  "steps": [
    {
      "object": "integration.setup_session.step",
      "status": "configured",
      "provider": {
        "object": "provider#preview",
        "id": "pro_5gHjKlMnPqRsTuVw",
        "name": "GitHub",
        "description": "Connect to GitHub repositories, issues, and pull requests",
        "slug": "github",
        "created_at": "2025-09-15T10:30:00.000Z",
        "updated_at": "2026-01-10T14:45:00.000Z"
      }
    },
    {
      "object": "integration.setup_session.step",
      "status": "configured",
      "provider": {
        "object": "provider#preview",
        "id": "pro_5gHjKlMnPqRsTuVw",
        "name": "GitHub",
        "description": "Connect to GitHub repositories, issues, and pull requests",
        "slug": "github",
        "created_at": "2025-09-15T10:30:00.000Z",
        "updated_at": "2026-01-10T14:45:00.000Z"
      }
    }
  ]
}

List integration setup sessions

Returns a paginated list of integration setup sessions.

Query Parameters

limit

NumberOptional

after

StringOptional

before

StringOptional

cursor

StringOptional

order

EnumOptional

status

UnionOptional

integration_id

UnionOptional

integration_instance_id

UnionOptional

created_at

ObjectOptional

Filter integration setup session creation time by date range

updated_at

ObjectOptional

Filter integration setup session last update time by date range

GEThttp://api.metorial.com/integration-setup-sessions

cURL

curl -X GET "https://api.metorial.com/integration-setup-sessions" \
  -H "Authorization: Bearer metorial_sk_..."

Get integration setup session

Retrieves a specific integration setup session.

URL Parameters

integration_setup_session_id

String

The unique identifier for the integration_setup_session

GEThttp://api.metorial.com/integration-setup-sessions/:integration_setup_session_id

cURL

curl -X GET "https://api.metorial.com/integration-setup-sessions/int_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_..."

Create integration setup session

Creates a new integration setup session and draft integration instance.

Request Body

integration_id

String

name

String

description

StringOptional

metadata

ObjectOptional

A key-value map

private_metadata

ObjectOptional

A key-value map

identity_actor_id

StringOptionalNullable

identity_id

StringOptionalNullable

expires_at

DateOptional

redirect_url

StringOptional

configuration

ObjectOptional

POSThttp://api.metorial.com/integration-setup-sessions

cURL

curl -X POST "https://api.metorial.com/integration-setup-sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
  "integration_id": "example_integration_id",
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "private_metadata": {},
  "identity_actor_id": "example_identity_actor_id",
  "identity_id": "example_identity_id",
  "expires_at": "2026-05-13T21:04:15.333Z",
  "redirect_url": "example_redirect_url",
  "configuration": {
    "provider_search": {
      "groups": {
        "group_id": "example_group_id"
      },
      "collections": {
        "collection_id": "example_collection_id"
      },
      "categories": {
        "category_id": "example_category_id"
      }
    },
    "tool_filters": {
      "enabled": false
    },
    "ui": {
      "layout": "box"
    }
  }
}'