Discover OIDC provider
Fetch and normalize OpenID Connect discovery metadata from an issuer.
POST /v1/providers/discover Fetch and normalize OpenID Connect discovery metadata from an issuer.
Performs OpenID Connect Discovery 1.0 against an issuer URL and returns the normalized result alongside reachability checks for the JWKS endpoint.
Request
| Field | Type | Required | Description |
|---|---|---|---|
| issuer | string (URL) | yes | Issuer URL. JWTShield fetches {issuer}/.well-known/openid-configuration. Trailing slash is preserved. |
Response — 200
| Field | Type | Required | Description |
|---|---|---|---|
| discovery | object | null | yes | Normalized metadata (see fields below). null when discovery itself failed. |
| discovery.issuer | string | yes | Canonical issuer URL as advertised in the metadata document. |
| discovery.jwks_uri | string | null | yes | JWKS endpoint URL. null if absent from metadata. |
| discovery.authorization_endpoint | string | null | yes | OAuth authorize endpoint, when present. |
| discovery.token_endpoint | string | null | yes | Token exchange endpoint, when present. |
| discovery.supported_algs | string[] | yes | Algorithms advertised in id_token_signing_alg_values_supported. |
| jwks_reachability | "reachable" | "unreachable" | "timeout" | yes | Result of the JWKS HEAD request. |
| findings | Finding[] | yes | Discovery-time issues. Empty on a clean discovery + reachable JWKS. |
| status | "ok" | "partial" | "failed" | yes | "ok": discovery + JWKS reachable. "partial": discovery succeeded but JWKS unreachable. "failed": discovery itself failed. |
200 successful discovery against an Auth0 tenant
{
"discovery": {
"issuer": "https://acme.auth0.com/",
"jwks_uri": "https://acme.auth0.com/.well-known/jwks.json",
"authorization_endpoint": "https://acme.auth0.com/authorize",
"token_endpoint": "https://acme.auth0.com/oauth/token",
"supported_algs": [
"RS256"
]
},
"jwks_reachability": "reachable",
"findings": [],
"status": "ok"
} Discovery is a network call
This endpoint reaches out to the issuer’s HTTP server. Cache results client-side; production verifiers should refresh discovery at a slow cadence (hours), not per-request.
Errors
| Channel | Code | Cause |
|---|---|---|
| 200, in findings | DISCOVERY_FAILED | /.well-known/openid-configuration returned non-2xx, non-JSON, or did not respond. |
| 200, in findings | JWKS_UNREACHABLE | Discovered jwks_uri did not respond with 2xx. |
| 200, in findings | INVALID_METADATA | Metadata document is JSON but does not match the OIDC Discovery 1.0 schema. |
| 422 | — | Request body missing issuer. |
Example
curl -sSf -X POST "$JWTSHIELD_URL/v1/providers/discover" \
-H "Authorization: Bearer $JWTSHIELD_KEY" \
-H "Content-Type: application/json" \
-d '{"issuer":"https://acme.auth0.com/"}'