MetorialDocs

Provider Setup Sessions

A setup session tracks an in-progress OAuth flow, storing state during the redirect. On success, it creates an auth config with the user's access token.

The Provider Setup Session object

provider_setup_session.json
{
  "object": "provider.setup_session",
  "id": "pas_6eFgHjKlMnPqRsTu",
  "type": "auth_only",
  "status": "failed",
  "url": "https://provider.metorial.com/setup/pas_6eFgHjKlMnPqRsTu",
  "name": "GitHub OAuth Setup",
  "description": "Connect your GitHub account",
  "metadata": {},
  "configuration": {},
  "provider_id": "pro_5gHjKlMnPqRsTuVw",
  "identity_id": "idn_3nOpRsTuVwXyZaBc",
  "identity_credential_id": "idc_3nOpRsTuVwXyZaBc",
  "owner_actor": {
    "id": "iac_6wQpLk2mZa8nYx4b",
    "type": "person",
    "consumer_id": "con_8kLmNp3qRs7tUv1w"
  },
  "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"
      }
    ],
    "adapters": [
      "example_adapters"
    ],
    "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"
  },
  "deployment": {
    "object": "provider.deployment#preview",
    "id": "pde_1aBcDeFgHjKlMnPq",
    "is_default": false,
    "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"
  },
  "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": {},
    "scopes": [
      "read",
      "write"
    ],
    "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",
    "id": "pac_8pQrStUvWxYzAbCd",
    "type": "manual",
    "source": "manual",
    "status": "active",
    "is_default": false,
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "name": "GitHub OAuth Token",
    "description": "OAuth token for GitHub API access",
    "metadata": {},
    "tool_filter": {
      "type": "allow_all",
      "ignore_parent_filters": false
    },
    "deployment": {
      "object": "provider.deployment#preview",
      "id": "pde_1aBcDeFgHjKlMnPq",
      "is_default": false,
      "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"
    },
    "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": {},
      "scopes": [
        "read",
        "write"
      ],
      "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"
        }
      ],
      "adapters": [
        "example_adapters"
      ],
      "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"
    },
    "owner_actor": {
      "id": "iac_6wQpLk2mZa8nYx4b",
      "type": "person",
      "consumer_id": "con_8kLmNp3qRs7tUv1w"
    },
    "created_at": "2025-09-15T10:30:00.000Z",
    "updated_at": "2026-01-10T14:45:00.000Z"
  },
  "config": {
    "object": "provider.config",
    "id": "pcf_7dEfGhJkLmNpQrSt",
    "status": "active",
    "is_default": false,
    "name": "Production Config",
    "description": "Configuration for production environment",
    "metadata": {},
    "tool_filter": {
      "type": "allow_all",
      "ignore_parent_filters": false
    },
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "specification_id": "psp_9gHjKlMnPqRsTuVw",
    "deployment": {
      "object": "provider.deployment#preview",
      "id": "pde_1aBcDeFgHjKlMnPq",
      "is_default": false,
      "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"
    },
    "from_vault": {
      "object": "provider.config_vault",
      "id": "pcvt_3bCdEfGhJkLmNpQr",
      "status": "active",
      "name": "Production Secrets",
      "description": "Secure storage for production credentials",
      "metadata": {},
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "deployment": {
        "object": "provider.deployment#preview",
        "id": "pde_1aBcDeFgHjKlMnPq",
        "is_default": false,
        "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"
      },
      "created_at": "2025-09-15T10:30:00.000Z",
      "updated_at": "2026-01-10T14:45:00.000Z"
    },
    "owner_actor": {
      "id": "iac_6wQpLk2mZa8nYx4b",
      "type": "person",
      "consumer_id": "con_8kLmNp3qRs7tUv1w"
    },
    "created_at": "2025-09-15T10:30:00.000Z",
    "updated_at": "2026-01-10T14:45:00.000Z"
  },
  "ui_mode": "metorial_elements",
  "redirect_url": "https://app.example.com/callback",
  "created_at": "2025-09-15T10:30:00.000Z",
  "updated_at": "2026-01-10T14:45:00.000Z",
  "expires_at": "2025-09-15T11:30:00.000Z"
}
object"provider.setup_session"required
idstringrequired
type"auth_only" | "config_only" | "auth_and_config"required
status"failed" | "archived" | "deleted" | "pending" | "completed" | "expired"required
urlstringrequired
namestringrequirednullable
descriptionstringrequirednullable
metadataRecord<string, any>requirednullable
configurationRecord<string, any>requirednullable
provider_idstringrequirednullable
identity_idstringrequirednullable
identity_credential_idstringrequirednullable
ui_mode"metorial_elements" | "dashboard_embeddable"required
redirect_urlstringrequirednullable
created_atdaterequired
updated_atdaterequired
expires_atdaterequired

Endpoints

List provider setup sessions

GET/provider-setup-sessions

Returns a paginated list of provider setup sessions.

Query parameters

idstring or string[]optional

Filter by setup session ID(s)

provider_idstring or string[]optional

Filter by provider ID(s)

provider_deployment_idstring or string[]optional

Filter by provider deployment ID(s)

provider_auth_method_idstring or string[]optional

Filter by auth method ID(s)

provider_auth_config_idstring or string[]optional

Filter by provider auth config ID(s)

provider_auth_credentials_idstring or string[]optional

Filter by provider auth credentials ID(s)

status"archived" | "failed" | "completed" | "expired" | "pending" or "archived" | "failed" | "completed" | "expired" | "pending"[]optional

Filter by session status (archived, failed, completed, expired, pending)

Example request

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

Get provider setup session

GET/provider-setup-sessions/:provider_setup_session_id

Retrieves a specific provider setup session by ID.

Path parameters

provider_setup_session_idstringrequired

The unique identifier for the provider_setup_session

Example request

curl -X GET "https://api.metorial.com/provider-setup-sessions/pro_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."

Create provider setup session

POST/provider-setup-sessions

Creates a new provider setup session for OAuth authentication.

Request body

provider_idstringoptional

The provider ID

provider_deployment_idstringoptional

Optional provider deployment ID

namestringoptional
descriptionstringoptional
metadataRecord<string, any>optional

Custom key-value pairs for storing additional information

provider_auth_method_idstringoptional

The authentication method to use (e.g., OAuth flow)

provider_auth_credentials_idstringoptional

Optional OAuth app credentials to use instead of defaults

identity_idstringoptional

Optional identity to link this setup session to

consumer_idstringoptional

Optional consumer to link this setup session to

redirect_urlstringoptional
type"auth_only" | "config_only" | "auth_and_config" | "auto"optional

The type of setup session, determining the flow and outcome of the session

Example request

curl -X POST "https://api.metorial.com/provider-setup-sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "provider_id": "pro_5gHjKlMnPqRsTuVw",
  "provider_deployment_id": "pdp_4dEfGhJkLmNpQrSt",
  "name": "GitHub OAuth Setup",
  "description": "Connect your GitHub account",
  "metadata": {},
  "provider_auth_method_id": "pam_2mNpQrStUvWxYzAb",
  "provider_auth_credentials_id": "pac_3nOpRsTuVwXyZaBc",
  "identity_id": "idn_3nOpRsTuVwXyZaBc",
  "consumer_id": "con_1a2b3c4d5e6f7g8h",
  "redirect_url": "https://app.example.com/oauth/callback",
  "type": "auth_only",
  "configuration": {
    "provider_search": {
      "groups": [
        {},
        {}
      ],
      "collections": [
        {},
        {}
      ],
      "categories": [
        {},
        {}
      ]
    },
    "tool_filters": {
      "enabled": false
    },
    "ui": {
      "layout": "box"
    }
  }
}'

Update provider setup session

PATCH/provider-setup-sessions/:provider_setup_session_id

Updates a specific provider setup session.

Path parameters

provider_setup_session_idstringrequired

The unique identifier for the provider_setup_session

Request body

namestringoptional
descriptionstringoptional
metadataRecord<string, any>optional

Custom key-value pairs for storing additional information

identity_idstringoptional

Optional identity to link this setup session to

Example request

curl -X PATCH "https://api.metorial.com/provider-setup-sessions/pro_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "Updated Setup Session",
  "description": "Updated setup session description",
  "metadata": {},
  "identity_id": "idn_3nOpRsTuVwXyZaBc"
}'

Delete provider setup session

DELETE/provider-setup-sessions/:provider_setup_session_id

Deletes a provider setup session.

Path parameters

provider_setup_session_idstringrequired

The unique identifier for the provider_setup_session

Example request

curl -X DELETE "https://api.metorial.com/provider-setup-sessions/pro_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."