Configure an external provider

POST

/options/authentication/external

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

Authorization

API-Key

headerX-API-KEY<token>

MonoCloud APIs require authentication with an API key. Retrieve your key from the Tenant Settings section of the MonoCloud dashboard and include it in the request header as: X-API-Key: <your_api_key>

Request Body

application/json

The request payload used to configure the external provider.

TypeScript Definitions

Use the request body type in TypeScript.

Create External Provider Request: Used to create an external authenticator.

name*string

The unique logical name of the connection. Identifies the connection and addresses it through the API.

Match^[a-z0-9]+([a-z0-9_-]+[a-z0-9])?$

Length1 <= length <= 20

authenticator*ExternalAuthenticators

The external identity provider of the connection.

values

google
Sign in with Google
apple
Sign in with Apple
facebook
Sign in with Facebook
microsoft
Sign in with Microsoft
github
Sign in with GitHub
gitlab
Sign in with GitLab
discord
Sign in with Discord
twitter
Sign in with Twitter
linkedin
Sign in with LinkedIn
xero
Sign in with Xero
custom_oidc
Sign in with a custom OIDC provider
custom_enterprise
Sign in with a custom enterprise SSO connection
entra_oidc
Sign in with Microsoft Entra ID (enterprise)

display_name?|

A custom display name for the provider's sign-in button. When not set, the provider's default display name is used.

Lengthlength <= 20

icon?|

A custom icon URL for the provider's sign-in button. When not set, the provider's default icon is used.

Formaturi

Lengthlength <= 400

enable_sign_in?boolean

Specifies whether users can sign in using this external identity provider.

Defaulttrue

enable_sign_up?boolean

Specifies whether new users can sign up using this external identity provider.

Defaulttrue

show_on_login_page?boolean

Specifies whether the provider's sign-in button is shown on the login page.

Defaulttrue

credentials?null|

connection?null|

scopes?array<>

The set of scopes requested from the external identity provider during authentication.

Itemsitems <= 100

Default[]

claim_mappings?

A map of claim names to upstream source claim names used to map the upstream profile onto the MonoCloud user.

authorization_parameters?

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?TrustIdentifierModes

Determines whether the email received from the external provider is treated as verified.

Default"as_provided"

values

as_provided
The email is treated as verified based on the email_verified claim received from the external provider.
never
The email is never treated as verified.
always
The email is always treated as verified.

trust_phone?TrustIdentifierModes

Determines whether the email received from the external provider is treated as verified.

Default"as_provided"

values

as_provided
The email is treated as verified based on the email_verified claim received from the external provider.
never
The email is never treated as verified.
always
The email is always treated as verified.

sync_user_profile_always?boolean

Specifies whether the user profile should be synchronized from the external provider on each successful sign-in.

Defaulttrue

sync_idp_claims_always?boolean

Specifies whether the IdP claims should be synchronized from the external provider on each successful sign-in.

Defaulttrue

home_realm_domains?array<string>

The email domains routed to this provider through home realm discovery.

Itemsitems <= 25

Default[]

priority?integer

The priority of the external provider. Used to order the provider relative to others.

Formatint32

Default0

Response Headers

201

location?string

Returns the location header

Formaturi

Response Body

201

application/json

The external provider was configured successfully

TypeScript Definitions

Use the response body type in TypeScript.

External Provider Response: Represents the configuration of an external authenticator.

name*string

The unique logical name of the connection. Identifies the connection and addresses it through the API.

authenticator*ExternalAuthenticators

The external identity provider of the connection.

values

google
Sign in with Google
apple
Sign in with Apple
facebook
Sign in with Facebook
microsoft
Sign in with Microsoft
github
Sign in with GitHub
gitlab
Sign in with GitLab
discord
Sign in with Discord
twitter
Sign in with Twitter
linkedin
Sign in with LinkedIn
xero
Sign in with Xero
custom_oidc
Sign in with a custom OIDC provider
custom_enterprise
Sign in with a custom enterprise SSO connection
entra_oidc
Sign in with Microsoft Entra ID (enterprise)

display_name?|

A custom display name for the provider's sign-in button. When not set, the provider's default display name is used.

icon?|

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

Specifies whether users can sign in using this external identity provider.

enable_sign_up*boolean

Specifies whether new users can sign up using this external identity provider.

show_on_login_page*boolean

Specifies whether the provider's sign-in button is shown on the login page.

credentials?null|

connection?null|

scopes*array<string>

The set of scopes requested from the external identity provider during authentication.

claim_mappings*

A map of claim names to upstream source claim names used to map the upstream profile onto the MonoCloud user.

authorization_parameters*

trust_email*TrustIdentifierModes

Determines whether the email received from the external provider is treated as verified.

values

as_provided
The email is treated as verified based on the email_verified claim received from the external provider.
never
The email is never treated as verified.
always
The email is always treated as verified.

trust_phone*TrustIdentifierModes

Determines whether the email received from the external provider is treated as verified.

values

as_provided
The email is treated as verified based on the email_verified claim received from the external provider.
never
The email is never treated as verified.
always
The email is always treated as verified.

sync_user_profile_always*boolean

Specifies whether the user profile should be synchronized from the external provider on each successful sign-in.

sync_idp_claims_always*boolean

Specifies whether the IdP claims should be synchronized from the external provider on each successful sign-in.

home_realm_domains*array<string>

The email domains routed to this provider through home realm discovery.

priority*integer

The priority of the external provider. Used to order the provider relative to others.

Formatint32

Errors

401Unauthorized

403Forbidden

curl -X POST "https://your-domain.us.monocloud.com/api/options/authentication/external" \  -H "X-API-KEY: <token>" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "authenticator": "custom_enterprise"  }'

{  "name": "string",  "authenticator": "custom_enterprise",  "display_name": null,  "icon": null,  "enable_sign_in": true,  "enable_sign_up": true,  "show_on_login_page": true,  "credentials": null,  "connection": null,  "scopes": [    "string"  ],  "claim_mappings": {    "property1": "string",    "property2": "string"  },  "authorization_parameters": {    "property1": "string",    "property2": "string"  },  "trust_email": "as_provided",  "trust_phone": "as_provided",  "sync_user_profile_always": true,  "sync_idp_claims_always": true,  "home_realm_domains": [    "string"  ],  "priority": 0}

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response HeadersCopy Anchor Link

Response BodyCopy Anchor Link

ErrorsCopy Anchor Link

400Bad Request

422Unprocessable Entity

Authorization

Request Body

Response Headers

Response Body

Errors