Management API

Every answer is checked against the model shown here before it is sent, and no answer carries a member its model does not list. A member shown as any JSON is one whose shape belongs to somebody else, and says whose. .{key} is a key that is data, and [] an element of a list.

A refusal

Unless an operation below says otherwise, any status it does not list answers this:

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean    
status integer    
why string    

GET /admin-api/saml-idp-initiated

getSamlIdpInitiatedApplications

The SAML applications a sign-in may be started here for, with each one’s link

Every SAML 2.0 service provider and SAML 1.1 relying party in this realm for which an identity-provider-initiated sign-in would be ALLOWED: the realm’s saml2.idpInitiatedSso / saml11.idpInitiatedSso (off by default), unless the entry’s saml2IdpInitiatedSso / saml11IdpInitiatedSso says otherwise — asked through the function GET /launch/{app} asks, so a row here is never one the link refuses with STS-LAUNCH-0005. One row per application and family; an application on in both is two rows.

launchUrl is the link a person follows (/launch/{app}?protocol=, this realm’s, on the sign-in service’s listener) and endpoint the protocol’s own unsolicited endpoint the link hands the browser to. A row whose missing is not empty is switched on and cannot work yet — it has no registered assertion consumer service, and the link answers STS-LAUNCH-0006 — and is listed so that it can be fixed.

realmSwitches says whether each realm setting is on: with both off, only an entry’s own override can put a row here.

Paged on idpInitiatedPage and per, by identifier.

Mirrors GET /admin/saml2 on the admin console.

The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).

Scope: admin:read.

Parameters

Name In Type Required What it is
idpInitiatedPage query integer   Which page of idpInitiated to return, answered by idpInitiatedPaging. The applications, by identifier.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: One page of the applications, its paging and the realm’s two switches.

Member Type Required What it is
idpInitiated list    
idpInitiated[].attribute string    
idpInitiated[].endpoint string, or null    
idpInitiated[].entityId string    
idpInitiated[].identifier string    
idpInitiated[].label string    
idpInitiated[].launchUrl string    
idpInitiated[].missing list    
idpInitiated[].missing[] string    
idpInitiated[].name string    
idpInitiated[].protocol string    
idpInitiatedPaging object    
idpInitiatedPaging.firstRow integer    
idpInitiatedPaging.lastRow integer    
idpInitiatedPaging.noun string, or null    
idpInitiatedPaging.page integer    
idpInitiatedPaging.pages integer    
idpInitiatedPaging.param string, or null    
idpInitiatedPaging.perPage integer    
idpInitiatedPaging.total integer    
protocolEndpoints list    
protocolEndpoints[].listening boolean    
protocolEndpoints[].methods list, or string    
protocolEndpoints[].methods[] string    
protocolEndpoints[].name string    
protocolEndpoints[].registered boolean    
protocolEndpoints[].route string    
protocolEndpoints[].transport string    
protocolEndpoints[].url string    
realmSwitches list    
realmSwitches[].attribute string    
realmSwitches[].enabled boolean    
realmSwitches[].label string    
realmSwitches[].protocol string    
realmSwitches[].setting string    

GET /admin-api/saml2

getSaml2ServiceProviders

Every SAML 2.0 service provider, and the endpoints each is configured from

A full SAML 2.0 identity provider: HTTP Redirect, HTTP POST and HTTP POST SimpleSign for the AuthnRequest, and HTTP POST, HTTP Redirect, HTTP POST SimpleSign or HTTP Artifact for the Response, with a SOAP artifact resolution service behind the last.

Every service provider gets its own identity provider metadata — a distinct entityID and its own endpoints — and in development a document is minted for any entityID asked for, so nothing has to be provisioned before a service provider can be pointed at this service; in product every per-service-provider path is a 404 for an entityID that is not registered. That is why metadataUrl is on every row rather than being one constant.

This resource holds nothing: every row is an entry in ou=applications, the same one GET /admin-api/applications reports.

?sp=<entityID> returns one of them, with what has been recorded about it — and answers 200 with found: false for an entityID that is not registered — whose metadata is still served and whose AuthnRequest would still be answered, in development only.

The list reply carries mdqRefused: the entityIDs a request asked the Metadata Query responder to register and product mode refused (no trust anchor, or an answer that did not verify), newest first, paged by mdqRefusedPage.

The ?sp= reply also says what checking its requests’ signatures found (lastRequestVerification), what they are verified against (signingCertificates), the certificate a request carried that nobody has confirmed (observedSigningCertificate), whether signed requests are required of it and why (signedRequestsRequired), and everything consuming its metadata registered (metadata).

Mirrors GET /admin/saml2 on the admin console.

The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).

Scope: admin:read.

Parameters

Name In Type Required What it is
q query string   Part of a service provider’s entityID, case-insensitive, narrowing the list.
sp query string   One service provider, by its entityID.
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
mdqRefusedPage query integer   Which page of mdqRefused to return, answered by mdqRefusedPaging. The Metadata Query lookups refused in product mode (#112), newest first.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The service providers with the paging that found them, or one of them with its endpoints and its record.

Member Type Required What it is
arsUrl string    
artifactsAwaitingResolution number    
assertionConsumerServices list    
assertionConsumerServices[] string    
authentications number    
found boolean    
identifier string    
idpEntityId string, or null    
kind string    
lastRequestSigned boolean    
lastRequestVerification object    
lastRequestVerification.binding string    
lastRequestVerification.outcome string    
lastRequestVerification.signatureMethod string    
lastRequestVerification.weak boolean    
mdqRefused list    
mdqRefused[].count number    
mdqRefused[].entityId string    
mdqRefused[].firstAt string, or null    
mdqRefused[].lastAt string, or null    
mdqRefused[].why string    
mdqRefusedPaging object    
mdqRefusedPaging.firstRow integer    
mdqRefusedPaging.lastRow integer    
mdqRefusedPaging.noun string, or null    
mdqRefusedPaging.offset integer    
mdqRefusedPaging.page integer    
mdqRefusedPaging.pages integer    
mdqRefusedPaging.param string, or null    
mdqRefusedPaging.perPage integer    
mdqRefusedPaging.total integer    
metadata object    
metadata.assertionConsumerServices list    
metadata.assertionConsumerServices[].binding string    
metadata.assertionConsumerServices[].index string    
metadata.assertionConsumerServices[].isDefault boolean, or null    
metadata.assertionConsumerServices[].location string    
metadata.authnRequestsSigned boolean    
metadata.cacheDuration string    
metadata.consumed boolean    
metadata.consumedAt string    
metadata.encryptionCertificate boolean    
metadata.expired boolean    
metadata.expiresAt string    
metadata.how string    
metadata.mdqUrl string    
metadata.nameIdFormats list    
metadata.nameIdFormats[] string    
metadata.refresh object    
metadata.refresh.failingSince string    
metadata.refresh.failures number    
metadata.refresh.lastAttemptAt string    
metadata.refresh.lastSuccessAt string    
metadata.refresh.ok boolean    
metadata.refresh.why string    
metadata.refreshable boolean    
metadata.refresherEnabled boolean    
metadata.refresherRunning boolean    
metadata.signature string    
metadata.signingCertificateConfigured boolean    
metadata.singleLogoutServices list    
metadata.singleLogoutServices[].binding string    
metadata.singleLogoutServices[].location string    
metadata.singleLogoutServices[].responseLocation string    
metadata.staleAt string    
metadata.state string    
metadata.stateWhy string    
metadata.trustAnchorProblems list    
metadata.trustAnchorProblems[] string    
metadata.trustAnchors number    
metadata.url string    
metadata.validUntil string    
metadata.wantAssertionsEncrypted boolean    
metadata.wantAssertionsSigned boolean    
metadataUrl string    
name string    
nameIdFormats list    
nameIdFormats[] string    
observedSigningCertificate string    
paging object    
paging.firstRow integer    
paging.lastRow integer    
paging.noun string, or null    
paging.offset integer    
paging.page integer    
paging.pages integer    
paging.param string, or null    
paging.perPage integer    
paging.total integer    
protocolEndpoints list    
protocolEndpoints[].listening boolean    
protocolEndpoints[].methods list, or string    
protocolEndpoints[].methods[] string    
protocolEndpoints[].name string    
protocolEndpoints[].registered boolean    
protocolEndpoints[].route string    
protocolEndpoints[].transport string    
protocolEndpoints[].url string    
requestsHeldForSignIn number    
responseBindings list    
responseBindings[] string    
serviceProviders list    
serviceProviders[].arsUrl string    
serviceProviders[].assertionConsumerServices list    
serviceProviders[].assertionConsumerServices[] string    
serviceProviders[].authentications number    
serviceProviders[].firstSeen string    
serviceProviders[].identifier string    
serviceProviders[].idpEntityId string, or null    
serviceProviders[].lastRequestSigned boolean    
serviceProviders[].lastRequestVerification string    
serviceProviders[].lastSeen string    
serviceProviders[].metadataUrl string    
serviceProviders[].name string, or null    
serviceProviders[].nameIdFormats list    
serviceProviders[].nameIdFormats[] string    
serviceProviders[].responseBindings list    
serviceProviders[].responseBindings[] string    
serviceProviders[].sessions number    
serviceProviders[].singleLogoutServices list    
serviceProviders[].singleLogoutServices[] string    
serviceProviders[].sloUrl string    
serviceProviders[].slug string, or null    
serviceProviders[].ssoUrl string    
serviceProviders[].users number    
settings object    
settings.context object    
settings.context.configFile string, or null    
settings.context.defaultsFile string, or null    
settings.context.inRealm boolean    
settings.context.persistenceMode string    
settings.context.persistsAppconfig boolean    
settings.context.persistsRealms boolean    
settings.context.realmId string, or null    
settings.editableCount integer    
settings.groups list    
settings.groups[].group string    
settings.groups[].settings list    
settings.groups[].settings[].appconfigPath string    
settings.groups[].settings[].csvValueNotes map   The sentence beside each value.
settings.groups[].settings[].csvValueNotes.{key} string    
settings.groups[].settings[].csvValues list    
settings.groups[].settings[].csvValues[] string    
settings.groups[].settings[].default list, or boolean, or number, or string, or null    
settings.groups[].settings[].default[] string    
settings.groups[].settings[].description string    
settings.groups[].settings[].editRefusal string    
settings.groups[].settings[].editable boolean    
settings.groups[].settings[].enumValues list    
settings.groups[].settings[].enumValues[] string    
settings.groups[].settings[].env string, or null    
settings.groups[].settings[].group string    
settings.groups[].settings[].key string    
settings.groups[].settings[].label string    
settings.groups[].settings[].legacyEnv string, or null    
settings.groups[].settings[].masked boolean    
settings.groups[].settings[].max number    
settings.groups[].settings[].min number    
settings.groups[].settings[].ordered boolean    
settings.groups[].settings[].overridden boolean    
settings.groups[].settings[].realmSettable boolean    
settings.groups[].settings[].restartReason string    
settings.groups[].settings[].selectAll map   The rules by kind: onlyWhileOn and aloneWhileOn.
settings.groups[].settings[].selectAll.{key} list    
settings.groups[].settings[].selectAll.{key}[].canBeOn object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.{key}[].on object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.{key}[].setting object   Nested deeper than this page draws.
settings.groups[].settings[].selectAll.{key}[].values object   Nested deeper than this page draws.
settings.groups[].settings[].source string    
settings.groups[].settings[].step number    
settings.groups[].settings[].text string, or null    
settings.groups[].settings[].type string    
settings.groups[].settings[].value list, or boolean, or number, or string, or null    
settings.groups[].settings[].value[] string    
settings.overridden list    
settings.overridden[] string    
settings.page string    
settings.setWith string    
settings.settingCount integer    
settings.sharedWith map   The other pages, by settings group.
settings.sharedWith.{key} list    
settings.sharedWith.{key}[].label string    
settings.sharedWith.{key}[].path string    
signedRequestsRequired object    
signedRequestsRequired.required boolean    
signedRequestsRequired.why string    
signingCertificate string    
signingCertificates list    
signingCertificates[] string    
singleLogoutServices list    
singleLogoutServices[] string    
sloUrl string    
slug string, or null    
ssoUrl string    
unscopedMetadata string    

POST /admin-api/saml2/confirm-signing-certificate

confirmSaml2SigningCertificate

Trust the certificate a signed request carried

A signed request’s ds:KeyInfo certificate that is not registered is recorded as OBSERVED (observedSigningCertificate on GET /admin-api/saml2?sp=, the attribute samlObservedSigningCertificate) and verifies NOTHING — anybody can sign a request and attach the key that verifies it. Development mode still encrypts an assertion to it when nothing else is on the entry; product does not.

This MOVES it onto samlSigningCertificate, so this service provider’s signatures are verified against it from the next request. Refused when nothing is observed, and for a certificate whose key signs nothing this service verifies. Confirm only a key you know is the service provider’s: this is the registration.

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
sp string yes  

200: The application entry as it now stands.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

POST /admin-api/saml2/discard-signing-certificate

discardSaml2SigningCertificate

Discard the certificate a signed request carried

The opposite answer to confirm-signing-certificate: the observed certificate is taken off the entry. It was never trusted; a signed request carrying it again records it again. Refused when nothing is observed.

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
sp string yes  

200: The application entry as it now stands.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

POST /admin-api/saml2/mdq-import

importSaml2MetadataFromMdq

Import a service provider from the MDQ responder

Asks saml2.mdqBaseUrl for <base>/entities/<percent-encoded entityID> (the Metadata Query Protocol), and — when the answer describes that entity — creates the application entry if it does not exist and consumes the document, held to the realm’s saml2.metadataTrustAnchors. Refused with no responder configured; an entry it created is removed again if the document is refused. In product mode with no trust anchor it is refused unless saml2.mdqImportWithoutAnchors is on, and then the reply carries warnings: the document was consumed with no signature check.

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
sp string yes  

200: What was consumed (with created), or why nothing was.

Member Type Required What it is
application string    
assertionConsumerServices list    
assertionConsumerServices[] string    
authnRequestsSigned boolean    
cacheDuration string, or null    
certificateUse string    
created boolean    
entityId string    
errors list    
errors[] string    
how string    
message string    
nameIdFormats list    
nameIdFormats[] string    
ok boolean yes  
signature string    
signingCertificates number    
singleLogoutServices list    
singleLogoutServices[] string    
skipped list    
skipped[] string    
url string    
validUntil string, or null    
wantAssertionsSigned boolean    
warnings list    
warnings[] string    
why string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
application string    
assertionConsumerServices list    
assertionConsumerServices[] string    
authnRequestsSigned boolean    
cacheDuration string, or null    
certificateUse string    
created boolean    
entityId string    
errors list    
errors[] string    
how string    
message string    
nameIdFormats list    
nameIdFormats[] string    
ok boolean yes  
signature string    
signingCertificates number    
singleLogoutServices list    
singleLogoutServices[] string    
skipped list    
skipped[] string    
url string    
validUntil string, or null    
wantAssertionsSigned boolean    
warnings list    
warnings[] string    
why string    

POST /admin-api/saml2/refresh-metadata

refreshSaml2Metadata

Fetch a service provider’s metadata again, now

Fetches the document from the entry’s samlSpMetadataUrl — or, for an entry with none, from the realm’s Metadata Query responder (saml2.mdqBaseUrl) — through the federation outbound policy, and CONSUMES it exactly as upload-metadata does. The background refresher does the same once a document is past its cacheDuration. A failure changes nothing.

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
sp string yes  

200: What was consumed, or why nothing was.

Member Type Required What it is
application string    
assertionConsumerServices list    
assertionConsumerServices[] string    
authnRequestsSigned boolean    
cacheDuration string, or null    
certificateUse string    
created boolean    
entityId string    
errors list    
errors[] string    
how string    
message string    
nameIdFormats list    
nameIdFormats[] string    
ok boolean yes  
signature string    
signingCertificates number    
singleLogoutServices list    
singleLogoutServices[] string    
skipped list    
skipped[] string    
url string    
validUntil string, or null    
wantAssertionsSigned boolean    
warnings list    
warnings[] string    
why string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
application string    
assertionConsumerServices list    
assertionConsumerServices[] string    
authnRequestsSigned boolean    
cacheDuration string, or null    
certificateUse string    
created boolean    
entityId string    
errors list    
errors[] string    
how string    
message string    
nameIdFormats list    
nameIdFormats[] string    
ok boolean yes  
signature string    
signingCertificates number    
singleLogoutServices list    
singleLogoutServices[] string    
skipped list    
skipped[] string    
url string    
validUntil string, or null    
wantAssertionsSigned boolean    
warnings list    
warnings[] string    
why string    

POST /admin-api/saml2/register

registerSaml2ServiceProvider

Register a service provider by entityID

OPTIONAL, and it changes nothing about whether a request is accepted: this identity provider accepts any entityID, and the first AuthnRequest or metadata fetch creates the entry anyway. What registering early buys is a metadata document to hand somebody before they have sent anything.

It is refused for an entityID that is already in the registry — an identifier names ONE application here whatever protocol brought it, so the answer to “it is already there” is to change what it holds rather than to create it twice.

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
sp string yes The service provider’s entityID.

200: The application entry, and where its metadata is served.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

POST /admin-api/saml2/remove-logout-service

removeSaml2LogoutService

Take a logout return address off a service provider

The attribute holds a LIST, so values are removed by name rather than the list being replaced. Removing the last one puts the fallback back.

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
sp string yes  
value string yes The exact value to remove.

200: The application entry as it now stands.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

POST /admin-api/saml2/remove-signing-certificate

removeSaml2SigningCertificate

Take one registered signing certificate off a service provider

By value — the base64 DER exactly as GET /admin-api/saml2?sp= lists it in signingCertificates (a PEM is accepted and normalised). Signatures made with that key stop verifying from the next request. Removing the last one leaves this service provider’s signatures recorded as no-certificate and not verified.

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
sp string yes  
value string yes The certificate to remove.

200: The application entry as it now stands.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

POST /admin-api/saml2/set-logout-service

addSaml2LogoutService

Declare where this service provider’s LogoutResponse goes

A <samlp:LogoutRequest> CARRIES NO RETURN ADDRESS — only SP metadata does. The SingleLogoutService endpoints of the service provider’s CONSUMED metadata are used first; with none, what is declared here; then the profile falls back to saml2.defaultSingleLogoutService and then to the assertion consumer service URL that service provider last used, WHICH IS A GUESS and is logged as one. This is how to remove the guess.

It writes samlSingleLogoutService on the application entry, so an ldapmodify of the same attribute does exactly this — two doors onto one value, not two stores.

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
sp string yes The service provider’s entityID.
value string yes An absolute URL.

200: The application entry as it now stands.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

POST /admin-api/saml2/set-metadata-signing-certificate

setSaml2MetadataSigningCertificate

Require this service provider’s metadata to be signed with one key

Writes samlSpMetadataSigningCertificate. With it set, consuming a metadata document — a refresh or an upload — REFUSES one that is unsigned or whose signature does not verify against this certificate, and changes nothing. Without it a signed document is consumed and recorded as signed-not-verified: the trust act is then the administrator’s choice of URL or document. Base64 DER or PEM, any key an XML signature is verified with here; empty clears it. The realm’s saml2.metadataTrustAnchors are accepted as well.

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
sp string yes  
value string   Base64 DER or PEM; empty clears it.

200: The application entry as it now stands.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

POST /admin-api/saml2/set-signing-certificate

setSaml2SigningCertificate

Replace the certificates this service provider’s signatures are verified against

THE TRUST ANCHOR FOR THIS SERVICE PROVIDER’S SIGNATURES (2026-09-17). A signed AuthnRequest, LogoutRequest or LogoutResponse from it is VERIFIED against samlSigningCertificate in every mode, and refused when it verifies against none — never against the certificate the request carries. The attribute is a LIST (a metadata rollover publishes two keys); this REPLACES it with the one certificate given, and an empty value clears it. Consuming the service provider’s metadata writes the same list.

Base64 DER or PEM — the armour and whitespace are stripped, because what the attribute holds is what a ds:X509Certificate carries. A value that is not a certificate whose key makes an XML signature this service verifies (RSA, EC, EdDSA, DSA, ML-DSA, SLH-DSA) is refused and nothing changes: an unusable certificate would make every signature from this service provider fail. Public key material, worth nothing to whoever reads the directory.

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
sp string yes  
value string   Base64 DER or PEM; empty clears the list.

200: The application entry as it now stands.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
application object    
application.allowedProtocols list    
application.allowedProtocols[] string    
application.attributes map   Attribute names, which are data in a schemaless directory, and values.
application.attributes.{key} list, or string, or null    
application.attributes.{key}[] string    
application.authentications number    
application.createdAt string, or null    
application.declaredKinds list    
application.declaredKinds[] string    
application.description string, or null    
application.dn string, or null    
application.dnLabel string, or null    
application.fields map   Attribute names, which are data in a schemaless directory, and values.
application.fields.{key} list, or string, or null    
application.fields.{key}[] string    
application.firstSeen string    
application.identifier string    
application.kinds list    
application.kinds[] string    
application.lastSeen string    
application.modifiedAt string, or null    
application.name string, or null    
application.operational list    
application.operational[] string    
application.origin string, or null    
application.protocols list    
application.protocols[] string    
application.recordedProtocols list    
application.recordedProtocols[] string    
application.registered boolean    
application.registeredBy string    
application.returnAddressesObserved list    
application.returnAddressesObserved[].attribute string    
application.returnAddressesObserved[].held boolean    
application.returnAddressesObserved[].trusted boolean    
application.returnAddressesObserved[].value string    
application.sessions number    
application.users number    
changed boolean    
errors list    
errors[] string    
message string    
ok boolean yes  

POST /admin-api/saml2/upload-metadata

uploadSaml2Metadata

Consume a service provider’s metadata document

The same CONSUMPTION POST /admin-api/applications/refresh-metadata performs on a fetched document, for a document given here — a service provider whose metadata this service cannot reach. It REGISTERS what the <md:SPSSODescriptor> says: every AssertionConsumerService (binding, location, index, isDefault) as a return address — an AuthnRequest is then answered only at one of them, by index, by URL or by default, in every mode — every SingleLogoutService, every signing certificate (use="signing" or no use) as what its requests are verified against, the encryption certificate, its NameIDFormats (a NameIDPolicy naming another is then InvalidNameIDPolicy), and AuthnRequestsSigned and WantAssertionsSigned. The EFFECTIVE validUntil (earliest in the chain) is enforced — past it every request from the service provider is refused — and past the cacheDuration a document with a URL is fetched again in the background. An EntitiesDescriptor is read for this entity. The protocol URI is selected from the application declaration: SAML 1.1 is selected only for an entry declared for saml11 and not saml2; SAML 2.0 remains the choice for SAML 2.0, dual-protocol and undeclared entries unless family explicitly selects one declared SAML family. This operation can therefore consume SAML 1.1-only metadata as well.

REFUSED, changing nothing, for: a document that is not an EntityDescriptor (or an aggregate holding exactly one for this entity) with the selected SPSSODescriptor; an entityID that is not this service provider’s; a validUntil already passed; an encryption certificate this service cannot encrypt to; a signature that does not verify against samlSpMetadataSigningCertificate or a realm trust anchor when any is set (or no signature then); and a document over saml2.spMetadataMaxBytes. A signing certificate no XML signature method uses is skipped and named in skipped.

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
(the answer) any JSON    

200: What was consumed: signature, the endpoint locations, how many signing certificates were registered, and skipped.

Member Type Required What it is
application string    
assertionConsumerServices list    
assertionConsumerServices[] string    
authnRequestsSigned boolean    
cacheDuration string, or null    
certificateUse string    
created boolean    
entityId string    
errors list    
errors[] string    
how string    
message string    
nameIdFormats list    
nameIdFormats[] string    
ok boolean yes  
signature string    
signingCertificates number    
singleLogoutServices list    
singleLogoutServices[] string    
skipped list    
skipped[] string    
url string    
validUntil string, or null    
wantAssertionsSigned boolean    
warnings list    
warnings[] string    
why string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
application string    
assertionConsumerServices list    
assertionConsumerServices[] string    
authnRequestsSigned boolean    
cacheDuration string, or null    
certificateUse string    
created boolean    
entityId string    
errors list    
errors[] string    
how string    
message string    
nameIdFormats list    
nameIdFormats[] string    
ok boolean yes  
signature string    
signingCertificates number    
singleLogoutServices list    
singleLogoutServices[] string    
skipped list    
skipped[] string    
url string    
validUntil string, or null    
wantAssertionsSigned boolean    
warnings list    
warnings[] string    
why string