MEmetorial
Provider Setup Sessions

Create provider setup session

Creates a new provider setup session for OAuth authentication.

post/provider-setup-sessions

Request

  • Base URL
    https://api.metorial.com
  • Auth
    HTTP bearer

Headers

Metorial-Versionstring
Example:2025-01-01

Pin the dated API version for this request, e.g. 2025-01-01. Defaults to the version configured for the environment.

Request body

provider_idstring

The provider ID

provider_deployment_idstring

Optional provider deployment ID

namestring
descriptionstring
metadataobject

Custom key-value pairs for storing additional information

provider_auth_method_idstring

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

provider_auth_credentials_idstring

Optional OAuth app credentials to use instead of defaults

identity_idstring

Optional identity to link this setup session to

consumer_idstring

Optional consumer to link this setup session to

redirect_urlstring
type'auth_only' | 'config_only' | 'auth_and_config' | 'admin' | 'auto'

The type of setup session, determining the flow and outcome of the session. admin creates an admin consent link for auth methods that support it, never creates credentials or configs, and cannot be bound to an identity, consumer, or config.

Example request

{
  "provider_id": "pro_5gHjKlMnPqRsTuVw",
  "provider_deployment_id": "pdp_4dEfGhJkLmNpQrSt",
  "name": "GitHub OAuth Setup",
  "description": "Connect your GitHub account",
  "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"
}

Response

Successful response

object'provider.setup_session' required

String representing the object's type

idstring required

Unique setup session identifier

type'auth_only' | 'config_only' | 'auth_and_config' | 'admin' required

Setup session type. admin sessions produce an admin consent link and complete without creating credentials.

status'failed' | 'archived' | 'deleted' | 'pending' | 'completed' | 'expired' required

Session status

urlstring required

URL where user completes authentication

namestring nullable required

Display name

descriptionstring nullable required

Description

metadataobject nullable required

Custom key-value pairs

configurationobject nullable required

Setup session configuration

provider_idstring nullable required

Provider ID

identity_idstring nullable required

Linked identity ID

identity_credential_idstring nullable required

Identity credential created from this setup session

ui_mode'metorial_elements' | 'dashboard_embeddable' required

UI mode for setup

redirect_urlstring nullable required

URL to redirect after setup

created_atstring date-time required

Timestamp when created

updated_atstring date-time required

Timestamp when last updated

expires_atstring date-time required

Timestamp when the session expires

Example response

{
  "id": "pas_6eFgHjKlMnPqRsTu",
  "url": "https://provider.metorial.com/setup/pas_6eFgHjKlMnPqRsTu",
  "error": {
    "code": "consent_required",
    "message": "consent_required: AADSTS90094: Admin consent is required."
  },
  "name": "GitHub OAuth Setup",
  "description": "Connect your GitHub account",
  "provider_id": "pro_5gHjKlMnPqRsTuVw",
  "identity_id": "idn_3nOpRsTuVwXyZaBc",
  "identity_credential_id": "idc_3nOpRsTuVwXyZaBc",
  "auth_method": {
    "id": "pam_2mNpQrStUvWxYzAb",
    "key": "oauth2",
    "name": "OAuth 2.0",
    "description": "Authenticate using OAuth 2.0",
    "scopes": [
      {
        "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": {
    "id": "pde_1aBcDeFgHjKlMnPq",
    "name": "Production",
    "description": "Production deployment",
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "created_at": "2025-09-15T10:30:00.000Z",
    "updated_at": "2026-01-10T14:45:00.000Z"
  },
  "credentials": {
    "id": "par_4sTuVwXyZaBcDeFg",
    "is_default": true,
    "is_managed": true,
    "name": "GitHub OAuth",
    "description": "OAuth credentials for GitHub API",
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "created_at": "2025-09-15T10:30:00.000Z",
    "updated_at": "2026-01-10T14:45:00.000Z"
  },
  "auth_config": {
    "id": "pac_8pQrStUvWxYzAbCd",
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "name": "GitHub OAuth Token",
    "description": "OAuth token for GitHub API access",
    "deployment": {
      "id": "pde_1aBcDeFgHjKlMnPq",
      "name": "Production",
      "description": "Production deployment",
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "created_at": "2025-09-15T10:30:00.000Z",
      "updated_at": "2026-01-10T14:45:00.000Z"
    },
    "credentials": {
      "id": "par_4sTuVwXyZaBcDeFg",
      "is_default": true,
      "is_managed": true,
      "name": "GitHub OAuth",
      "description": "OAuth credentials for GitHub API",
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "created_at": "2025-09-15T10:30:00.000Z",
      "updated_at": "2026-01-10T14:45:00.000Z"
    },
    "auth_method": {
      "id": "pam_2mNpQrStUvWxYzAb",
      "key": "oauth2",
      "name": "OAuth 2.0",
      "description": "Authenticate using OAuth 2.0",
      "scopes": [
        {
          "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": {
    "id": "pcf_7dEfGhJkLmNpQrSt",
    "name": "Production Config",
    "description": "Configuration for production environment",
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "specification_id": "psp_9gHjKlMnPqRsTuVw",
    "deployment": {
      "id": "pde_1aBcDeFgHjKlMnPq",
      "name": "Production",
      "description": "Production deployment",
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "created_at": "2025-09-15T10:30:00.000Z",
      "updated_at": "2026-01-10T14:45:00.000Z"
    },
    "from_vault": {
      "id": "pcvt_3bCdEfGhJkLmNpQr",
      "name": "Production Secrets",
      "description": "Secure storage for production credentials",
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "deployment": {
        "id": "pde_1aBcDeFgHjKlMnPq",
        "name": "Production",
        "description": "Production deployment",
        "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"
  },
  "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"
}

Changes

No recorded changes to this operation across all 1 revision of this API.