--- title: "Create a New Authenticator Configuration" method: POST path: "/v1/tenants/{tenant_id}/realms/{realm_id}/authenticator-configs" tags: ["Authenticator Configurations"] --- # Create a New Authenticator Configuration `POST /v1/tenants/{tenant_id}/realms/{realm_id}/authenticator-configs` ## Request - Base URL: `https://api-us.beyondidentity.com` - URL: `https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/authenticator-configs` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) To create an authenticator configuration, send a POST request to `/v1/tenants/$TENANT_ID/realms/$REALM_ID/authenticator-configs`. Values in the request body for read-only fields will be ignored. ## Path parameters - `tenant_id` string, required - `realm_id` string, required ## Request body - object: Request for CreateAuthenticatorConfig. - `authenticator_config` AuthenticatorConfig, required: Representation of an authenticator configuration. This prescribes how an identity may authenticate themselves with Beyond Identity. - `id` string: A unique identifier for an authenticator configuration. This is automatically generated on creation. This field is immutable and read-only. This field is unique within the realm. - `realm_id` string: A unique identifier for the authenticator configuration's realm. This is automatically set on creation. This field is immutable and read-only. - `tenant_id` string: A unique identifier for the authenticator configuration's tenant. This is automatically set on creation. This field is immutable and read-only. - `display_name` string: A human-readable name for the authenticator configuration. This name is used for display purposes. - `config` union: An object specifying the settings for the supported authenticator type. - object: Configuration options for the embedded SDK authenticator. - `invocation_type` 'automatic' | 'manual': The method used to invoke the `invoke_url` in the embedded authenticator config type. The two methods available are: The value `automatic` indicates that this invocation type automatically redirects you to your native or web app using the Invoke URL with a challenge that your app will need to sign. The value `manual` indicates that this invocation type will cause the challenge to be returned to you as part of a JSON response. It will then be up to you to get it to your native/web app any way you see fit. This is useful for flows where you require a lot more control when redirecting to your native/web app. Since the challenge is packaged as part of a URL, following the URL will result in the same behavior as if an Invocation Type of "automatic" were selected. - `invoke_url` string, required: URL to invoke during the authentication flow. - `trusted_origins` string[], required: Trusted origins are URLs that will be allowed to make requests from a browser to the Beyond Identity API. This is used with Cross-Origin Resource Sharing (CORS). These may be in the form of ` "://" [ ":" ]`, such as `https://auth.your-domain.com` or `http://localhost:3000`. - `type` 'embedded', required - `authentication_methods` object[] - `type` 'email_one_time_password' | 'software_passkey' | 'webauthn_passkey', required: Within our hosted web product, an array of values determines the client-side authentication workflows: The value `webauthn_passkey` triggers a workflow that generates a hardware key within your device's trusted execution environment (TEE). If webauthn passkeys are not supported in the browser, specifying one of the other two authentication methods will result in a fallback to that mechanism. The value `software_passkey` activates a workflow where a passkey is securely created within the browser's context. The value `email_one_time_password` enables a workflow that verifies identity via an email of a one-time password. - object: Configuration options for the hosted web experience. This authenticator is maintained by Beyond Identity and allows the caller to customize authentication methods. - `authentication_methods` Items[], required (unresolved $ref) - `trusted_origins` string[], required: Trusted origins are URLs that will be allowed to make requests from a browser to the Beyond Identity API. This is used with Cross-Origin Resource Sharing (CORS). These may be in the form of ` "://" [ ":" ]`, such as `https://auth.your-domain.com` or `http://localhost:3000`. - `type` 'hosted_web', required - object: Configuration options for credential enrollment, enabling an identity to access the Beyond Identity Console. These options support both IDP-authorized flows and non-verified enrollment pathways. - `type` 'console', required - `onboarding_configuration` object, required: Configuration options for the console onboarding experience. - `verification_method` union, required - object: Configures IDP verification for identities onboarding. - … - object: An onboarding configuration with no verification configured. Identities will not be verified during the onboarding operation. - … - object: Configuration options for the platform authenticator. - `type` 'platform', required - `trusted_origins` string[], nullable: Trusted origins are URLs that will be allowed to make requests from a browser to the Beyond Identity API. This is used with Cross-Origin Resource Sharing (CORS). These may be in the form of ` "://" [ ":" ],` such as `https://auth.your-domain.com` or `http://localhost:3000`. - `roaming_auth_config` object: The roaming_auth_config offers advanced configuration options for the roaming auth feature. - `enabled` boolean, required: If false, roaming auth is never offered as an available flow during authentication on this Authenticator Config. - `allow_unknown_user` boolean: If a login_hint is not provided or the login_hint does not match for exactly one user in the directory, the user will be considered "unknown" and the value of allow_unknown_user will be used to determine whether or not to offer roaming auth. - `allowed_source_ips` string[]: If allowed_source_ips is not null and not empty, roaming auth will only be offered to users who begin the authentication from a specified IP address or range. - `allowed_user_group_ids` string[]: If allowed_user_group_ids is not nil and not empty, roaming auth will only be offered to users if they are part of one of those user groups. Note that the user is determined _before_ authentication using a best effort lookup by login_hint, if provided. If a login_hint is not provided or the login_hint does not match for exactly one user in the directory, the user will be considered \"unknown\" and the value of allow_unknown_user will be used to determine whether or not to offer roaming auth. - `allowed_user_ids` string[]: If allowed_user_ids is not nil and not empty, roaming auth will only be offered to specified users. Note that the user is determined _before_ authentication using a best effort lookup by login_hint, if provided. If a login_hint is not provided or the login_hint does not match for exactly one user in the directory, the user will be considered \"unknown\" and the value of allow_unknown_user will be used to determine whether or not to offer roaming auth. ## Response `200` The response will be a JSON object containing the standard attributes associated with an authenticator configuration. - AuthenticatorConfig: Representation of an authenticator configuration. This prescribes how an identity may authenticate themselves with Beyond Identity. - `id` string: A unique identifier for an authenticator configuration. This is automatically generated on creation. This field is immutable and read-only. This field is unique within the realm. - `realm_id` string: A unique identifier for the authenticator configuration's realm. This is automatically set on creation. This field is immutable and read-only. - `tenant_id` string: A unique identifier for the authenticator configuration's tenant. This is automatically set on creation. This field is immutable and read-only. - `display_name` string: A human-readable name for the authenticator configuration. This name is used for display purposes. - `config` union: An object specifying the settings for the supported authenticator type. - object: Configuration options for the embedded SDK authenticator. - `invocation_type` 'automatic' | 'manual': The method used to invoke the `invoke_url` in the embedded authenticator config type. The two methods available are: The value `automatic` indicates that this invocation type automatically redirects you to your native or web app using the Invoke URL with a challenge that your app will need to sign. The value `manual` indicates that this invocation type will cause the challenge to be returned to you as part of a JSON response. It will then be up to you to get it to your native/web app any way you see fit. This is useful for flows where you require a lot more control when redirecting to your native/web app. Since the challenge is packaged as part of a URL, following the URL will result in the same behavior as if an Invocation Type of "automatic" were selected. - `invoke_url` string, required: URL to invoke during the authentication flow. - `trusted_origins` string[], required: Trusted origins are URLs that will be allowed to make requests from a browser to the Beyond Identity API. This is used with Cross-Origin Resource Sharing (CORS). These may be in the form of ` "://" [ ":" ]`, such as `https://auth.your-domain.com` or `http://localhost:3000`. - `type` 'embedded', required - `authentication_methods` object[] - `type` 'email_one_time_password' | 'software_passkey' | 'webauthn_passkey', required: Within our hosted web product, an array of values determines the client-side authentication workflows: The value `webauthn_passkey` triggers a workflow that generates a hardware key within your device's trusted execution environment (TEE). If webauthn passkeys are not supported in the browser, specifying one of the other two authentication methods will result in a fallback to that mechanism. The value `software_passkey` activates a workflow where a passkey is securely created within the browser's context. The value `email_one_time_password` enables a workflow that verifies identity via an email of a one-time password. - object: Configuration options for the hosted web experience. This authenticator is maintained by Beyond Identity and allows the caller to customize authentication methods. - `authentication_methods` Items[], required (unresolved $ref) - `trusted_origins` string[], required: Trusted origins are URLs that will be allowed to make requests from a browser to the Beyond Identity API. This is used with Cross-Origin Resource Sharing (CORS). These may be in the form of ` "://" [ ":" ]`, such as `https://auth.your-domain.com` or `http://localhost:3000`. - `type` 'hosted_web', required - object: Configuration options for credential enrollment, enabling an identity to access the Beyond Identity Console. These options support both IDP-authorized flows and non-verified enrollment pathways. - `type` 'console', required - `onboarding_configuration` object, required: Configuration options for the console onboarding experience. - `verification_method` union, required - object: Configures IDP verification for identities onboarding. - `type` 'idp', required: The type of verification method to be used for credential onboarding. Currently only `idp` or `none` are supported options. If set to `none` there will be no verification step performed for the identity selected for credential onboarding. - `idp_id` string, uuid, required: The id of the IDP to use to verify the identity during the onboarding process. - object: An onboarding configuration with no verification configured. Identities will not be verified during the onboarding operation. - `type` 'none', required: The type of verification method to be used for credential onboarding. Currently only `idp` or `none` are supported options. If set to `none` there will be no verification step performed for the identity selected for credential onboard. - object: Configuration options for the platform authenticator. - `type` 'platform', required - `trusted_origins` string[], nullable: Trusted origins are URLs that will be allowed to make requests from a browser to the Beyond Identity API. This is used with Cross-Origin Resource Sharing (CORS). These may be in the form of ` "://" [ ":" ],` such as `https://auth.your-domain.com` or `http://localhost:3000`. - `roaming_auth_config` object: The roaming_auth_config offers advanced configuration options for the roaming auth feature. - `enabled` boolean, required: If false, roaming auth is never offered as an available flow during authentication on this Authenticator Config. - `allow_unknown_user` boolean: If a login_hint is not provided or the login_hint does not match for exactly one user in the directory, the user will be considered "unknown" and the value of allow_unknown_user will be used to determine whether or not to offer roaming auth. - `allowed_source_ips` string[]: If allowed_source_ips is not null and not empty, roaming auth will only be offered to users who begin the authentication from a specified IP address or range. - `allowed_user_group_ids` string[]: If allowed_user_group_ids is not nil and not empty, roaming auth will only be offered to users if they are part of one of those user groups. Note that the user is determined _before_ authentication using a best effort lookup by login_hint, if provided. If a login_hint is not provided or the login_hint does not match for exactly one user in the directory, the user will be considered \"unknown\" and the value of allow_unknown_user will be used to determine whether or not to offer roaming auth. - `allowed_user_ids` string[]: If allowed_user_ids is not nil and not empty, roaming auth will only be offered to specified users. Note that the user is determined _before_ authentication using a best effort lookup by login_hint, if provided. If a login_hint is not provided or the login_hint does not match for exactly one user in the directory, the user will be considered \"unknown\" and the value of allow_unknown_user will be used to determine whether or not to offer roaming auth. ## Other responses - `400`: Bad request. - `401`: Unauthorized. - `403`: Forbidden. - `404`: The resource was not found. - `500`: Server error. ## Changes - **2026-11-06** `42f3cac49392`: 1 breaking, 1 info - added `subschema #3: Console Authenticator, subschema #4: Platform Authenticator` to the `config` response property `oneOf` list for the response status `200` - added `subschema #3: Console Authenticator, subschema #4: Platform Authenticator` to the `authenticator_config/config` request property `oneOf` list [Operation history](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/changes/v1/tenants/:tenant_id/realms/:realm_id/authenticator-configs/post.md) --- [API](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api.md) - [All operations](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/llms.txt) - [OpenAPI document](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/revisions/42f3cac49392?raw)