Promote next SAML signing certificate.
curl --request POST \ --url https://auth.example.com/api/admin/saml-providers/example/signing-rollover/promote-next \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "certificate": "-----BEGIN CERTIFICATE-----...", "metadataCertificatePublication": "active_next" }'Promotes the provider signing policy next certificate to active and can retain the previous active certificate as backup.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”SAML provider id.
Request Body required
Section titled “Request Body required ”object
Example
{ "certificate": "-----BEGIN CERTIFICATE-----...", "metadataCertificatePublication": "active_next"}Responses
Section titled “ Responses ”Successful JSON response.
object
object
object
URL-backed providers default to automatic when this property is omitted.
True when metadata lifecycle automation disabled the provider.
For a service provider (saml_sp): the lowest identity assurance level (NIST SP 800-63A IAL) a person may have to sign in to it. A person below it gets no assertion: an SP-initiated request is answered with a Responder/RequestDenied status (to the ACS URL, signed as other error responses are, with the RelayState), an IdP-initiated sign-in with the error page. If the person’s evidence cannot be read, the answer is a Responder status without a second-level code (SP-initiated) or a server error (IdP-initiated), never an assertion. The answer does not say what level the person holds or the SP requires. Applies whether or not tenant-wide assurance (assurance.enabled) is on, and does not use the scope-to-IAL requirements, which are OAuth scopes. On create, absent or null sets none; on update, absent leaves it, null removes it and an empty string is refused. Any value other than IAL1, IAL2, IAL3 or null is refused with 400. A saml_idp provider refuses it. The identity assurance values (eduPersonAssurance) and the IAL itself are released to an SP through its Field Mapping Set (the system sources assurance_ial and edu_person_assurance), not through this setting.
For a service provider (saml_sp): the lowest authentication assurance level (NIST SP 800-63B AAL) a sign-in may have for it. A sign-in below it is sent to authenticate again once (a step-up: the person is sent to the re-authentication page, which is given force_authn, required_aal and a challenge_id, and the factors of the session stepped up from are combined with the new sign-in’s); if the person comes back still below it, the SP-initiated request is answered with Responder/NoAuthnContext (to the ACS URL, signed as other error responses are, with the RelayState), never sent again. A passive request (IsPassive) is answered with Responder/NoPassive and is not sent. An IdP-initiated sign-in below it gets the error page (it has no request to step up). The answer does not say what level the sign-in reached or the SP requires. Applies whether or not tenant-wide assurance (assurance.enabled) is on; the AAL a request’s RequestedAuthnContext asks for (assurance.saml_authn_context_aal) is added to it while assurance is on, and the higher applies. On create, absent or null sets none; on update, absent leaves it, null removes it and an empty string is refused. Any value other than AAL1, AAL2, AAL3 or null is refused with 400. A saml_idp provider refuses it. The bundled login UI carries the step-up out: the challenge_id given to the re-authentication page (/reauth, as for an OIDC prompt=login) is a re-authentication for the person who is signed in, bound to the AuthnRequest, the SP and the tenant, so the request is not completed with the session the person already has; they authenticate again as the same user with a method the tenant allows for re-authentication (passkey, email code or TOTP whose authentication-methods re-authentication setting is on, whatever their sign-in setting), and a session proven before the step-up began is never counted. A factor proven in the same session beside its older one counts as the new factor and is combined with the older, which stays old. A custom login UI has to do the same. The SP-initiated request is answered with Responder/AuthnFailed when a ForceAuthn sign-in did not happen, or when the person comes back from the re-authentication page with no session.
For a service provider (saml_sp): how the AuthnContextClassRef of an assertion is chosen. legacy_static (the default when absent) is the SP’s defaultAuthnContextClassRef or the IdP’s own; session is the class reference of the session’s authentication; assurance is the class reference that assurance.saml_authn_context_aal maps to the AAL the sign-in reached (the strongest the sign-in meets, among those the request’s Comparison accepts), falling back to the static choice when that table has none that fits or the request names references it does not list. Any other value is refused with 400.
object
Per-SP release mode for every attribute in the active SAML Destination Profile.
object
For an IdP (saml_idp): the profile fields a login from it updates for a user already linked to it, with external_idp.jit_update_on_login on. Null or absent follows the tenant’s external_idp.jit_update_fields; [] updates none. Names any of name, given_name, family_name, middle_name, nickname, profile, picture, website, gender, birthdate, zoneinfo and locale (after the field mapping), each once; any other value is refused with 400.
object
object
Example
{ "success": true, "config": { "entityId": "https://idp.example.com/metadata" }, "signingKeyPolicy": { "next": { "kid": "saml-next-key" } }, "updatedAt": "2026-06-19T00:00:00.000Z"}