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.

Provider Setup Sessions object

Attributes

object

String

String representing the object's type

id

String

Unique setup session identifier

type

Enum

Setup session type

status

Enum

Session status

url

String

URL where user completes authentication

name

StringNullable

Display name

description

StringNullable

Description

metadata

ObjectNullable

Custom key-value pairs

configuration

ObjectNullable

Setup session configuration

provider_id

StringNullable

Provider ID

identity_id

StringNullable

Linked identity ID

identity_credential_id

StringNullable

Identity credential created from this setup session

auth_method

ObjectNullable

deployment

ObjectNullable

credentials

ObjectNullable

auth_config

ObjectNullable

config

ObjectNullable

ui_mode

Enum

UI mode for setup

redirect_url

StringNullable

URL to redirect after setup

created_at

Date

Timestamp when created

updated_at

Date

Timestamp when last updated

expires_at

Date

Timestamp when the session expires

{
  "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",
  "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"
  },
  "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"
  },
  "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"
  },
  "auth_config": {
    "object": "provider.auth_config",
    "id": "pac_8pQrStUvWxYzAbCd",
    "type": "manual",
    "source": "manual",
    "status": "active",
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "name": "GitHub OAuth Token",
    "description": "OAuth token for GitHub API access",
    "metadata": {},
    "tool_filter": {
      "type": "allow_all"
    },
    "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"
    },
    "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"
    },
    "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"
    },
    "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",
    "name": "Production Config",
    "description": "Configuration for production environment",
    "metadata": {},
    "tool_filter": {
      "type": "allow_all"
    },
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "specification_id": "psp_9gHjKlMnPqRsTuVw",
    "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"
    },
    "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",
        "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"
    },
    "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"
}

List provider setup sessions

Returns a paginated list of provider setup sessions.

Query Parameters

limit

NumberOptional

after

StringOptional

before

StringOptional

cursor

StringOptional

order

EnumOptional

id

UnionOptional

Filter by setup session ID(s)

provider_id

UnionOptional

Filter by provider ID(s)

provider_deployment_id

UnionOptional

Filter by provider deployment ID(s)

provider_auth_method_id

UnionOptional

Filter by auth method ID(s)

provider_auth_config_id

UnionOptional

Filter by provider auth config ID(s)

provider_auth_credentials_id

UnionOptional

Filter by provider auth credentials ID(s)

status

UnionOptional

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

created_at

ObjectOptional

Filter provider setup session creation time by date range

updated_at

ObjectOptional

Filter provider setup session last update time by date range

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

Get provider setup session

Retrieves a specific provider setup session by ID.

URL Parameters

provider_setup_session_id

String

The unique identifier for the provider_setup_session

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

Create provider setup session

Creates a new provider setup session for OAuth authentication.

Request Body

provider_id

StringOptional

The provider ID

provider_deployment_id

StringOptional

Optional provider deployment ID

name

StringOptional

description

StringOptional

metadata

ObjectOptional

Custom key-value pairs for storing additional information

provider_auth_method_id

StringOptional

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

provider_auth_credentials_id

StringOptional

Optional OAuth app credentials to use instead of defaults

identity_id

StringOptional

Optional identity to link this setup session to

consumer_id

StringOptional

Optional consumer to link this setup session to

redirect_url

StringOptional

type

EnumOptional

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

configuration

ObjectOptional
POSThttp://api.metorial.com/provider-setup-sessions
curl -X POST "https://api.metorial.com/provider-setup-sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
  "provider_id": "example_provider_id",
  "provider_deployment_id": "example_provider_deployment_id",
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "provider_auth_method_id": "example_provider_auth_method_id",
  "provider_auth_credentials_id": "example_provider_auth_credentials_id",
  "identity_id": "example_identity_id",
  "consumer_id": "example_consumer_id",
  "redirect_url": "example_redirect_url",
  "type": "auth_only",
  "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"
    }
  }
}'

Update provider setup session

Updates a specific provider setup session.

URL Parameters

provider_setup_session_id

String

The unique identifier for the provider_setup_session

Request Body

name

StringOptional

description

StringOptional

metadata

ObjectOptional

Custom key-value pairs for storing additional information

identity_id

StringOptional

Optional identity to link this setup session to

PATCHhttp://api.metorial.com/provider-setup-sessions/:provider_setup_session_id
curl -X PATCH "https://api.metorial.com/provider-setup-sessions/pro_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "identity_id": "example_identity_id"
}'

Delete provider setup session

Deletes a provider setup session.

URL Parameters

provider_setup_session_id

String

The unique identifier for the provider_setup_session

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