MetorialDocs

Provider Auth Configs

An auth config is a user's authenticated connection to a provider. Created when a user completes OAuth or manually enters an API token.

The Provider Auth Config object

provider_auth_config.json
{
  "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"
}
object"provider.auth_config"required
idstringrequired
type"manual" | "oauth_automated" | "oauth_manual"required
source"manual" | "setup_session" | "system"required
status"active" | "archived" | "deleted"required
is_defaultbooleanrequired
provider_idstringrequired
namestringrequirednullable
descriptionstringrequirednullable
metadataRecord<string, any>requirednullable
created_atdaterequired
updated_atdaterequired

Endpoints

List provider auth configs

GET/provider-auth-configs

Returns a paginated list of provider auth configs.

Query parameters

status"active" | "archived" or "active" | "archived"[]optional

Filter by status (active, archived)

idstring or string[]optional

Filter by auth config ID(s)

provider_idstring or string[]optional

Filter by provider ID(s)

provider_deployment_idstring or string[]optional

Filter by provider deployment ID(s)

available_for_usebooleanoptional

Only return auth configs that are not owned by another integration instance provider.

available_for_provider_deployment_idstringoptional

Only return auth configs that are not locked to a different provider deployment.

provider_auth_credentials_idstring or string[]optional

Filter by auth credentials ID(s)

provider_auth_method_idstring or string[]optional

Filter by auth method ID(s)

actor_idstring or string[]optional

Filter by actor ID(s)

consumer_idstring or string[]optional

Filter by consumer ID(s)

identity_idstring or string[]optional

Filter by identity ID(s)

identity_credential_idstring or string[]optional

Filter by identity credential ID(s)

adapterstringoptional

Only return auth configs whose auth method supports this adapter

searchstringoptional

Search by name or description

Example request

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

Get provider auth config

GET/provider-auth-configs/:provider_auth_config_id

Retrieves a specific provider auth config by ID.

Path parameters

provider_auth_config_idstringrequired

The unique identifier for the provider_auth_config

Example request

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

Create provider auth config

POST/provider-auth-configs

Creates a new provider auth config.

Request body

namestringoptional
descriptionstringoptional
metadataRecord<string, any>optional

Custom key-value pairs for storing additional information

provider_auth_method_idstringrequired

The authentication method this config uses (e.g., OAuth, API key)

provider_deployment_idstringoptional

The provider deployment this auth config is associated with (if applicable)

valueRecord<string, any>required

Authentication config payload

Example request

curl -X POST "https://api.metorial.com/provider-auth-configs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "GitHub OAuth Token",
  "description": "OAuth token for GitHub API access",
  "metadata": {},
  "tool_filters": {
    "type": "tool_keys",
    "keys": [
      "example_keys"
    ]
  },
  "provider_auth_method_id": "pam_2mNpQrStUvWxYzAb",
  "provider_deployment_id": "pd_2mNpQrStUvWxYzAb",
  "value": {}
}'

Update provider auth config

PATCH/provider-auth-configs/:provider_auth_config_id

Updates a specific provider auth config.

Path parameters

provider_auth_config_idstringrequired

The unique identifier for the provider_auth_config

Request body

namestringoptional
descriptionstringoptional
metadataRecord<string, any>optional

Custom key-value pairs for storing additional information

Example request

curl -X PATCH "https://api.metorial.com/provider-auth-configs/pro_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "Updated Auth Config Name",
  "description": "Updated description for auth configuration",
  "metadata": {},
  "tool_filters": {
    "type": "tool_keys",
    "keys": [
      "example_keys"
    ]
  }
}'

Delete provider auth config

DELETE/provider-auth-configs/:provider_auth_config_id

Permanently deletes a provider auth config.

Path parameters

provider_auth_config_idstringrequired

The unique identifier for the provider_auth_config

Example request

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