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

status

String

Session status (pending, in_progress, completed, failed, expired)

name

StringNullable

Display name

description

StringNullable

Description

metadata

ObjectNullable

Custom key-value pairs for storing additional information

provider_id

String

Provider ID

provider_deployment_id

StringNullable

Deployment ID

provider_auth_method_id

String

Auth method ID

redirect_url

StringNullable

URL to redirect after setup

url

StringNullable

URL where user completes authentication

created_at

Date

Timestamp when created

updated_at

Date

Timestamp when last updated

expires_at

DateNullable

Timestamp when the session expires

auth_config

ObjectNullable
{
  "object": "provider.setup_session",
  "id": "pas_6eFgHjKlMnPqRsTu",
  "type": "oauth",
  "status": "pending",
  "name": "GitHub OAuth Setup",
  "description": "Connect your GitHub account",
  "metadata": {
    "redirect_uri": "https://app.example.com/callback",
    "requested_scopes": [
      "repo",
      "user"
    ]
  },
  "provider_id": "pro_5gHjKlMnPqRsTuVw",
  "provider_deployment_id": "pde_1aBcDeFgHjKlMnPq",
  "provider_auth_method_id": "pam_2mNpQrStUvWxYzAb",
  "redirect_url": "https://app.example.com/callback",
  "url": "https://provider.metorial.com/setup/pas_6eFgHjKlMnPqRsTu",
  "created_at": "2025-09-15T10:30:00.000Z",
  "updated_at": "2026-01-10T14:45:00.000Z",
  "expires_at": "2025-09-15T11:30:00.000Z",
  "auth_config": {
    "object": "provider.auth_config",
    "id": "pac_8pQrStUvWxYzAbCd",
    "type": "manual",
    "name": "GitHub OAuth Token",
    "description": "OAuth token for GitHub API access",
    "metadata": {
      "connected_by": "alex@company.com",
      "purpose": "ci-pipeline"
    },
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "provider_deployment_id": "pde_1aBcDeFgHjKlMnPq",
    "provider_auth_method_id": "pam_2mNpQrStUvWxYzAb",
    "created_at": "2025-09-15T10:30:00.000Z",
    "updated_at": "2026-01-10T14:45:00.000Z"
  }
}

List provider setup sessions

Returns a paginated list of provider setup sessions.

URL Parameters

provider_deployment_id

String

The unique identifier for the provider_deployment

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

provider_auth_method_id

UnionOptional

Filter by auth method ID(s)

status

StringOptional

Filter by session status

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

Get provider setup session

Retrieves a specific provider setup session by ID.

URL Parameters

provider_deployment_id

String

The unique identifier for the provider_deployment

provider_setup_session_id

String

The unique identifier for the provider_setup_session

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

Create provider setup session

Creates a new provider setup session for OAuth authentication.

URL Parameters

provider_deployment_id

String

The unique identifier for the provider_deployment

Request Body

name

StringOptional

description

StringOptional

metadata

ObjectOptional

Custom key-value pairs for storing additional information

providerAuthMethodId

String

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

providerAuthCredentialsId

StringOptional

Optional OAuth app credentials to use instead of defaults

redirectUrl

StringOptional
POSThttp://api.metorial.com/provider-deployments/:provider_deployment_id/setup-sessions
curl -X POST "https://api.metorial.com/provider-deployments/pro_Rm4Mnheq2bfEPhBhP7SY/setup-sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "providerAuthMethodId": "example_providerAuthMethodId",
  "providerAuthCredentialsId": "example_providerAuthCredentialsId",
  "redirectUrl": "example_redirectUrl"
}'

Update provider setup session

Updates a specific provider setup session.

URL Parameters

provider_deployment_id

String

The unique identifier for the provider_deployment

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-deployments/:provider_deployment_id/setup-sessions/:provider_setup_session_id
curl -X PATCH "https://api.metorial.com/provider-deployments/pro_Rm4Mnheq2bfEPhBhP7SY/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_deployment_id

String

The unique identifier for the provider_deployment

provider_setup_session_id

String

The unique identifier for the provider_setup_session

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