# Configure an external provider (/docs/apis/management/options/CreateExternalProvider)

`POST /options/authentication/external`

Configures a new external provider that end-users can authenticate with.

Base URL: `https://{tenant}.{region}.monocloud.com/api`, where `{tenant}`, `{region}` (one of us, eu, in) come from your tenant. Authentication: send your Management API key in the `X-API-KEY` header.

## Request body

JSON, required. The request payload used to configure the external provider.

- `name` (string, required) The unique logical name of the connection. Identifies the connection and addresses it through the API.
- `authenticator` (string, required) The external identity provider of the connection. One of: `google`, `apple`, `facebook`, `microsoft`, `github`, `gitlab`, `discord`, `twitter`, `linkedin`, `xero`, `custom_oidc`, `custom_enterprise`, `entra_oidc`.
- `display_name` (string) A custom display name for the provider's sign-in button. When not set, the provider's default display name is used.
- `icon` (string, uri) A custom icon URL for the provider's sign-in button. When not set, the provider's default icon is used.
- `enable_sign_in` (boolean, default true) Specifies whether users can sign in using this external identity provider.
- `enable_sign_up` (boolean, default true) Specifies whether new users can sign up using this external identity provider.
- `show_on_login_page` (boolean, default true) Specifies whether the provider's sign-in button is shown on the login page.
- `credentials` (CreateExternalProviderCredentialsRequest) The client credentials issued by the external identity provider. When not set, MonoCloud-managed credentials are used.
  - `client_id` (string, required) The client identifier issued by the external identity provider.
  - `client_secret` (string, required) The client secret issued by the external identity provider.
  - `apple_team_id` (string) The Apple Developer Team ID used to sign the client secret. Applies only to the Sign in with Apple provider.
  - `apple_key_id` (string) The Apple Key ID used to sign the client secret. Applies only to the Sign in with Apple provider.
- `connection` (CreateExternalProviderConnectionRequest) The protocol connection settings used to communicate with the external identity provider. Applies only to custom and enterprise connections.
  - `discovery_url` (string, required) The discovery (metadata) endpoint of the external provider. The provider endpoints are derived from the discovery document.
  - `pkce_mode` (string, default "auto") The PKCE mode used with the external provider. One of: `auto`, `s256`, `plain`, `none`.
- `scopes` (string[], default []) The set of scopes requested from the external identity provider during authentication.
- `claim_mappings` (Record<string, string>) A map of claim names to upstream source claim names used to map the upstream profile onto the MonoCloud user.
- `authorization_parameters` (Record<string, string>) A map of parameter names to the values sent to the external provider's authorization endpoint. A value prefixed with `$` forwards the incoming authorization request query parameter with that name; any other value is sent as-is.
- `trust_email` (string, default "as_provided") Determines whether the email received from the external provider is treated as verified. One of: `as_provided`, `never`, `always`.
- `trust_phone` (string, default "as_provided") Determines whether the phone number received from the external provider is treated as verified. One of: `as_provided`, `never`, `always`.
- `sync_user_profile_always` (boolean, default true) Specifies whether the user profile should be synchronized from the external provider on each successful sign-in.
- `sync_idp_claims_always` (boolean, default true) Specifies whether the IdP claims should be synchronized from the external provider on each successful sign-in.
- `home_realm_domains` (string[], default []) The email domains routed to this provider through home realm discovery.
- `priority` (integer, int32, default 0) The priority of the external provider. Used to order the provider relative to others.

## Response body

`201`, JSON. The external provider was configured successfully

Returns `ExternalProvider`.

- `name` (string, required) The unique logical name of the connection. Identifies the connection and addresses it through the API.
- `authenticator` (string, required) The external identity provider of the connection. One of: `google`, `apple`, `facebook`, `microsoft`, `github`, `gitlab`, `discord`, `twitter`, `linkedin`, `xero`, `custom_oidc`, `custom_enterprise`, `entra_oidc`.
- `display_name` (string) A custom display name for the provider's sign-in button. When not set, the provider's default display name is used.
- `icon` (string) A custom icon URL for the provider's sign-in button. When not set, the provider's default icon is used.
- `enable_sign_in` (boolean, required) Specifies whether users can sign in using this external identity provider.
- `enable_sign_up` (boolean, required) Specifies whether new users can sign up using this external identity provider.
- `show_on_login_page` (boolean, required) Specifies whether the provider's sign-in button is shown on the login page.
- `credentials` (ExternalProviderCredentialsResponse) The client credentials issued by the external identity provider. When not set, MonoCloud-managed credentials are used.
  - `client_id` (string, required) The client identifier issued by the external identity provider.
  - `apple_team_id` (string) The Apple Developer Team ID used to sign the client secret. Applies only to the Sign in with Apple provider.
  - `apple_key_id` (string) The Apple Key ID used to sign the client secret. Applies only to the Sign in with Apple provider.
- `connection` (ExternalProviderConnectionResponse) The protocol connection settings used to communicate with the external identity provider. Applies only to custom and enterprise connections.
  - `discovery_url` (string, required) The discovery (metadata) endpoint of the external provider. The provider endpoints are derived from the discovery document.
  - `pkce_mode` (string, required) The PKCE mode used with the external provider. One of: `auto`, `s256`, `plain`, `none`.
- `scopes` (string[], required) The set of scopes requested from the external identity provider during authentication.
- `claim_mappings` (Record<string, string>, required) A map of claim names to upstream source claim names used to map the upstream profile onto the MonoCloud user.
- `authorization_parameters` (Record<string, string>, required) A map of parameter names to the values sent to the external provider's authorization endpoint. A value prefixed with `$` forwards the incoming authorization request query parameter with that name; any other value is sent as-is.
- `trust_email` (string, required) Determines whether the email received from the external provider is treated as verified. One of: `as_provided`, `never`, `always`.
- `trust_phone` (string, required) Determines whether the phone number received from the external provider is treated as verified. One of: `as_provided`, `never`, `always`.
- `sync_user_profile_always` (boolean, required) Specifies whether the user profile should be synchronized from the external provider on each successful sign-in.
- `sync_idp_claims_always` (boolean, required) Specifies whether the IdP claims should be synchronized from the external provider on each successful sign-in.
- `home_realm_domains` (string[], required) The email domains routed to this provider through home realm discovery.
- `priority` (integer, required, int32) The priority of the external provider. Used to order the provider relative to others.

## Errors

- `400` Bad Request
  - `type` (string, required) A URI reference that identifies the error type. When accessed, it may provide human-readable documentation.
  - `title` (string, required) A short, human-readable summary of the error.
  - `status` (integer, required, int32) The HTTP status code associated with this error response.
  - `trace_id` (string, required) A unique identifier for the request, used for tracing and diagnostics.
  - `detail` (string) A human-readable explanation specific to this occurrence of the error.
  - `instance` (string) A URI reference that identifies the specific occurrence of the error.
- `401` Unauthorized
- `403` Forbidden
- `422` Unprocessable Entity
  - `type` (string, required) A URI reference that identifies the error type. When accessed, it may provide human-readable documentation.
  - `title` (string, required) A short, human-readable summary of the error.
  - `status` (integer, required, int32) The HTTP status code associated with this error response.
  - `trace_id` (string, required) A unique identifier for the request, used for tracing and diagnostics.
  - `detail` (string) A human-readable explanation specific to this occurrence of the error.
  - `instance` (string) A URI reference that identifies the specific occurrence of the error.
  - `errors` (Record<string, string[]>, required) A key-value map of validation errors, where each key represents a request field and the value contains one or more messages describing why the request could not be processed.

## Example (MonoCloud .NET SDK)

```csharp
using MonoCloud.Management;
using MonoCloud.Management.Models;
using MonoCloud.Management.Core.Base;

var apiClient = new MonoCloudManagementClient(new MonoCloudConfig("<your-domain>", "[[API-Key]]"));


var requestBody = new CreateExternalProviderRequest
  {
    Name = "acme",
    Authenticator = ExternalAuthenticators.CustomEnterprise,
    DisplayName = "Sign in with Acme",
    Icon = "https://cdn.acme.com/icons/sso.svg",
    EnableSignIn = true,
    EnableSignUp = true,
    ShowOnLoginPage = true,
    Credentials = new CreateExternalProviderCredentialsRequest
    {
      ClientId = "Lkidgf845hKHrfwehf_jgf",
      ClientSecret = "JJfgi4597fs9hkmkdfrk_jfhh4uuNBFl",
      AppleTeamId = "kjGD8745hasd",
      AppleKeyId = "styfderhrwe456",
    },
    Connection = new CreateExternalProviderConnectionRequest
    {
      DiscoveryUrl = "https://sso.acme.com/.well-known/openid-configuration",
      PkceMode = OidcPkceMode.Auto,
    },
    Scopes = new List<string>
    {
      "openid",
      "profile",
      "email",
    },
    ClaimMappings = new Dictionary<string, object>
    {
      {
        "email", "mail"
      },
      {
        "name", "displayName"
      },
    },
    AuthorizationParameters = new Dictionary<string, object>
    {
      {
        "login_hint", "$login_hint"
      },
      {
        "prompt", "consent"
      },
    },
    TrustEmail = TrustIdentifierModes.AsProvided,
    TrustPhone = TrustIdentifierModes.AsProvided,
    SyncUserProfileAlways = true,
    SyncIdpClaimsAlways = true,
    HomeRealmDomains = new List<string>
    {
      "acme.com",
      "acme.io",
    },
    Priority = 0,
  };


var result = await apiClient.Options.CreateExternalProviderAsync(requestBody);
```

## Example (MonoCloud Javascript SDK)

```javascript
import { MonoCloudManagementClient } from '@monocloud/management';

const apiClient = MonoCloudManagementClient.init({ domain: '<your-domain>', apiKey: '[[API-Key]]' });

const requestBody = {
  name: 'acme',
  authenticator: 'custom_enterprise',
  display_name: 'Sign in with Acme',
  icon: 'https://cdn.acme.com/icons/sso.svg',
  enable_sign_in: true,
  enable_sign_up: true,
  show_on_login_page: true,
  credentials: {
    client_id: 'Lkidgf845hKHrfwehf_jgf',
    client_secret: 'JJfgi4597fs9hkmkdfrk_jfhh4uuNBFl',
    apple_team_id: 'kjGD8745hasd',
    apple_key_id: 'styfderhrwe456'
  },
  connection: {
    discovery_url: 'https://sso.acme.com/.well-known/openid-configuration',
    pkce_mode: 'auto'
  },
  scopes: [
    'openid',
    'profile',
    'email'
  ],
  claim_mappings: {
    email: 'mail',
    name: 'displayName'
  },
  authorization_parameters: {
    login_hint: '$login_hint',
    prompt: 'consent'
  },
  trust_email: 'as_provided',
  trust_phone: 'as_provided',
  sync_user_profile_always: true,
  sync_idp_claims_always: true,
  home_realm_domains: [
    'acme.com',
    'acme.io'
  ],
  priority: 0
};

const result = apiClient.options.createExternalProvider(requestBody);
```