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

String

Setup session type

status

String

Session status

url

String

URL where user completes authentication

name

StringNullable

Display name

description

StringNullable

Description

metadata

ObjectNullable

Custom key-value pairs

provider_id

String

Provider ID

auth_method

Object

deployment

ObjectNullable

credentials

ObjectNullable

auth_config

ObjectNullable

config

ObjectNullable

ui_mode

String

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": "oauth",
  "status": "pending",
  "url": "https://provider.metorial.com/setup/pas_6eFgHjKlMnPqRsTu",
  "name": "GitHub OAuth Setup",
  "description": "Connect your GitHub account",
  "metadata": {
    "redirect_uri": "https://app.example.com/callback"
  },
  "provider_id": "pro_5gHjKlMnPqRsTuVw",
  "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"
      }
    ],
    "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",
    "is_default": true,
    "name": "GitHub OAuth",
    "description": "OAuth credentials for GitHub API",
    "metadata": {
      "app_name": "My GitHub App",
      "created_by": "[email protected]"
    },
    "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": {
      "connected_by": "[email protected]",
      "purpose": "ci-pipeline"
    },
    "deployment_preview": {
      "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",
      "is_default": true,
      "name": "GitHub OAuth",
      "description": "OAuth credentials for GitHub API",
      "metadata": {
        "app_name": "My GitHub App",
        "created_by": "[email protected]"
      },
      "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"
        }
      ],
      "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",
    "name": "Production Config",
    "description": "Configuration for production environment",
    "metadata": {
      "label": "primary",
      "notes": "Default production config"
    },
    "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",
      "name": "Production Secrets",
      "description": "Secure storage for production credentials",
      "metadata": {
        "owner": "platform-team",
        "sensitivity": "high"
      },
      "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": "redirect",
  "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

Maximum number of items to return (1-100)

after

StringOptional

Return items after this ID

before

StringOptional

Return items before this ID

cursor

StringOptional

Pagination cursor from a previous response

order

EnumOptional

Sort order for results

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)

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

String

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

redirect_url

StringOptional
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",
  "redirect_url": "example_redirect_url"
}'

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

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": {}
}'

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_..."