Check SAML Metadata
Read an IdP's metadata exactly as Add SAML IdP would, with the same checks, and see what it says: the IdP's entity ID, its sign-in address and its certificates. Nothing is stored. Use it to check the metadata before you add the SAML IdP. In the dashboard: Read in the SAML dialog.
Needs the endpoint_saml feature on the plan of the account that owns the endpoint (Enterprise) and the endpoints:write permission. Strict JSON decoding: unknown body fields return 400.
Path parameters
uuid string (uuid) Req
The endpoint's
uuid from /endpoints.An integer id in the path is refused with 400 integer_id_unsupported (see public IDs). Use the uuid.
Request body
Exactly one of:
metadata_url string
The IdP's metadata URL: https on a public address, answering within 15 seconds, without a redirect.
metadata_xml string
The IdP's metadata, pasted (at most 1 MiB).
Response (200 OK)
entity_id, sso_url string
The IdP's entity ID, and the address ngris would send sign-in requests to.
certificates array<object>
Its signing certificates:
sha256 (the fingerprint), subject, not_before, not_after.certs_not_after datetime?
When the last of them ends.
want_requests_signed boolean
The IdP asks for signed sign-in requests: ngris will sign them.
existing_idp_uuid string (uuid)?
Only when the endpoint has this IdP (its entity ID) already: adding it again is refused, so update that one instead.
Errors
400 Bad Request
Invalid JSON or unknown fields; both sources, or neither; or metadata ngris can't use, with the field and why, as for Add SAML IdP.
401 Unauthorized
Missing auth.
403 Forbidden
Caller lacks the
endpoints:write permission, the plan doesn't include SAML single sign-on ("entitlement_required": "endpoint_saml"), or the account is suspended.404 Not Found
Endpoint doesn't exist or doesn't belong to the calling account.
409 Conflict
The endpoint is paused.
413 Payload Too Large
The request is too large: paste at most 1 MiB of metadata, or give its URL.503 Service Unavailable
SAML single sign-on isn't available yet. Try again in a few minutes.Request
curl -X POST "https://api.ngris.com/v1/endpoints/019bb1e4-e785-77d2-9966-c3cff31d0a0e/saml/idps/read" \
-H "X-API-KEY: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{"metadata_url": "https://idp.example.com/metadata"}'
CLI
ngris api saml-idps read-metadata 019bb1e4-e785-77d2-9966-c3cff31d0a0e \
--metadata-url "https://idp.example.com/metadata"
Response
{
"entity_id": "https://idp.example.com/saml",
"sso_url": "https://idp.example.com/saml/sso",
"certificates": [{
"sha256": "3F:9A:…:C2",
"subject": "CN=idp.example.com",
"not_before": "2026-01-10T00:00:00Z",
"not_after": "2031-01-10T00:00:00Z"
}],
"certs_not_after": "2031-01-10T00:00:00Z",
"want_requests_signed": false
}
Was this helpful?