It provides a JSON document at a well-known location that describes the Identity Provider’s (IdP’s) capabilities and endpoints. Clients (RPs) can use this to automatically configure themselves instead of requiring manual configuration of URLs and supported features.
Endpoint
GET https://[BASE_URL]/.well-known/openid-configuration
Response
The response is a JSON object containing metadata about the IdP. Example:
Token Endpoint – Returns tokens signed with keys in the JWKS.
Authorization Endpoint
Overview
The Authorization Endpoint is the starting point for OAuth 2.0 and OpenID Connect flows. It handles user authentication and authorization, and issues an authorization code, implicit tokens, or an ID Token, depending on the flow.
Clients redirect the user’s browser to this endpoint with the appropriate query parameters. After the user authenticates (and consents if required), the IdP redirects the browser back to the client with the authorization response.
Endpoint
The endpoint is advertised in the authorization_endpoint in the metadata exposed by the discovery endpoint and typically is:
GET https://[BASE_URL]/connect/authorize
Parameters
Parameter
Required
Description
response_type
Yes
Defines which flow to use (code, id_token, token, or a combination).
client_id
Yes
The client identifier registered with the IdP.
redirect_uri
Yes
Where the user should be redirected after authentication. Must be pre-registered.
scope
Yes
Space-delimited list of scopes. Must include openid for OpenID Connect requests.
state
Recommended
Opaque value used to maintain request state and prevent CSRF. Returned unchanged in response.
nonce
Required for id_token
String used to associate client session with ID Token to prevent replay attacks.
The Pushed Authorization Request (PAR) Endpoint allows clients to securely push authorization request parameters directly to the Identity Provider (IdP) via a backchannel POST request.
Instead of sending all authorization parameters in the front-channel (via the browser), the client sends them to the IdP in advance. The IdP returns a short-lived request_uri reference. The client then uses this request_uri in the front-channel redirect to the Authorization Endpoint.
This improves security (no long query strings, prevents tampering) and reliability (handles large requests). The use of PAR is encouraged by the FAPI working group within the OpenID Foundation. For example, the FAPI2.0 Security Profile requires the use of PAR. This security profile is used by many of the groups working on open banking (primarily in Europe), in health care, and in other industries with high security requirements.
Endpoint
The endpoint is advertised in the pushed_authorization_request_endpoint in the metadata exposed by the discovery endpoint and typically is:
POST https://[BASE_URL]/connect/par
Parameters (form-encoded)
All parameters normally passed to the Authorization Endpoint (response_type, client_id, redirect_uri, scope, state, nonce, etc.) must be included in the PAR request.
Parameter
Required
Description
response_type
Yes
Defines the flow (code, id_token, etc.).
client_id
Yes
The client identifier registered with the IdP.
redirect_uri
Yes
Must match a registered redirect URI.
scope
Yes
Scopes requested (openid required for OIDC).
state
Recommended
Opaque value for request correlation/CSRF protection.
nonce
Required for id_token requests
Protects against replay attacks.
Full documentation of all authorization parameters can be found here.
Authentication
Confidential clients authenticate (e.g., HTTP Basic Auth or private_key_jwt).
Public clients may use PKCE (Proof Key for Code Exchange).
Response
A successful response returns JSON with a request_uri and its lifetime (expires_in):
Token Endpoint – Exchanges the code obtained after authorization.
Token Endpoint
Overview
The Token Endpoint is used by clients to exchange an authorization code, refresh tokens, or client credentials for OAuth 2.0 tokens (Access Token, Refresh Token, and optionally an ID Token).
It is typically called by back-end components (not the browser) using HTTPS POST requests.
Endpoint
The endpoint is advertised in the authorization_endpoint in the metadata exposed by the discovery endpoint and typically is:
POST https://[BASE_URL]/connect/token
Parameters (form-encoded)
Parameter
Required
Description
grant_type
Yes
The grant type (authorization_code, refresh_token, client_credentials, etc.).
code
Required for authorization_code
The authorization code received from the Authorization Endpoint.
redirect_uri
Required for authorization_code
Must match the original redirect_uri used in the request.
client_id
Required (if not using client authentication header)
The client identifier.
client_secret
Required (for confidential clients)
The client’s secret.
code_verifier
Required for PKCE
The original code verifier for PKCE-enabled flows.
refresh_token
Required for refresh_token grant
The refresh token issued earlier.
Response
Successful responses are JSON objects containing issued tokens, for example:
The Introspection Endpoint is defined in RFC 7662. It allows APIs (or clients) to query the IdP about the active state of an OAuth 2.0 token (Access Token or Refresh Token). Refresh tokens can only be introspected by the client that requested them.
This endpoint is useful for APIs that need to validate whether a token is still valid, and to obtain metadata about the token (e.g., scope, expiration, subject).
Endpoint
The endpoint is advertised in the introspection_endpoint in the metadata exposed by the discovery endpoint and typically is:
POST https://[BASE_URL]/connect/introspect
Parameters (form-encoded)
Parameter
Required
Description
token
Yes
The token to be introspected.
token_type_hint
Optional
A hint about the type of token (access_token or refresh_token).
Authentication
The introspection endpoint requires authentication. Since the request to the introspection endpoint is typically done by an API, which is not an OAuth client, the ApiResource is used to configure credentials. For a client the configured credentials of the client is used.
Response
Successful responses are JSON objects. If the token is active:
Unknown or expired tokens will be marked as inactive::
{
"active": false}
Usage Example
HTTP POST /introspect
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(api_resource:api_resource_secret)
token=[token]&token_type_hint=access_token
Return JWT Instead of JSON
Authway supports RFC 9701 to return a JWT response from the introspection endpoint.
To return a JWT response, set the Accept header in the HTTP request to application/token-introspection+jwt:
HTTP POST /connect/introspect
Accept: application/token-introspection+jwtAuthorization:
Authorization: Basic base64(api_resource:api_resource_secret)
token=[token]
A successful response will return a status code of 200 and has a Content-Type: application/token-introspection+jwt header, indicating that the response body contains a raw JWT instead. The base64 decoded JWT will have a typ claim in the header with the value token-introspection+jwt. The token’s payload contains a token_introspection JSON object similar to the default response type:
Token Endpoint – Issues tokens that may later be introspected.
UserInfo Endpoint – Provides user claims associated with an Access Token.
Token Revocation Endpoint
Overview
The Revocation Endpoint is defined in RFC 7009. It allows clients to notify the IdP that a previously issued Refresh Token or Access Token is no longer needed.
Revocation helps ensure tokens cannot be misused if they are leaked or when a session ends.
Endpoint
The endpoint is advertised in the revocation_endpoint in the metadata exposed by the discovery endpoint and typically is:
POST https://[BASE_URL]/connect/revocation
Parameters (form-encoded)
Parameter
Required
Description
token
Yes
The token to revoke (Access or Refresh Token).
token_type_hint
Optional
A hint about the type of token (access_token or refresh_token).
Authentication
The client must authenticate (e.g., Basic Auth with client_id and client_secret).
Response
A successful revocation request returns HTTP 200 OK with an empty body.
Even if the token is invalid or already revoked, the IdP returns 200 OK (to prevent token probing).
Usage Example
POST /connect/revocation
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)
token=8xLOxBtZp8&token_type_hint=refresh_token
Security Considerations
RPs should clear local session data after revoking tokens.
The UserInfo Endpoint is defined in the OpenID Connect Core specification. It returns claims about the authenticated end-user, given a valid Access Token obtained via OpenID Connect.
It allows clients to retrieve claims (e.g., sub, name, email).
Endpoint
The endpoint is advertised in the userinfo_endpoint in the metadata exposed by the discovery endpoint and typically is:
GET https://[BASE_URL]/connect/userinfo
Authentication
Requires an Access Token issued for the openid scope.
The token is sent in the Authorization header:
Authorization: Bearer SlAV32hkKG
Response
A successful response is a JSON object containing user claims. Example:
Token Endpoint – Exchanges authorization codes for Access Tokens.
Check Session iframe
Overview
The Check Session IFrame endpoint allows relying parties (RPs) to detect changes in the user’s authentication state at the Identity Provider (IdP). It is defined by the OpenID Connect Session Management specification.
RPs embed this endpoint in a hidden <iframe> within their application. The RP can then periodically send postMessage requests to the iframe to check whether the user’s session at the IdP is still valid.
Another option to silently check that a user is stilled signed in is by making an authentication request with prompt=none parameter. This will return a new ID token without user interaction, unless the user is no longer authenticated.
Endpoint
The endpoint is advertised in the check_session_iframe in the metadata exposed by the discovery endpoint and typically is:
GET https://[BASE_URL]/connect/checksession
Parameters
This endpoint does not accept query parameters directly. Instead, communication happens through HTML5 postMessage between the RP’s hidden iframe and the IdP’s check session iframe.
Usage
Obtain session_state:
When the RP receives an authorization response from the IdP, it will include a session_state value.
The RP stores this value for use in session checking.
The IdP responds back to the RP window with one of the following values:
"unchanged" – The session is still valid.
"changed" – The session has changed (e.g., user logged out at IdP).
"error" – Invalid message format or unrecognized client.
Example listener:
window.addEventListener("message", function(e) {
if (e.origin!=="https://[BASE_URL]") return;
if (e.data==="changed") {
// Trigger RP logout or silent reauthentication
}
}, false);
Security Considerations
Always validate the origin of the postMessage to ensure it matches the IdP domain.
The iframe should never be visible to end users.
Applications should define a clear flow for handling "changed" responses (e.g., logout the user, refresh tokens, or re-initiate login).
The End Session Endpoint allows relying parties (RPs) to sign the user out of the Identity Provider (IdP) and, optionally, to perform Single Logout (SLO) across multiple clients.
The RP can redirect the user’s browser to this endpoint to terminate the IdP session. The IdP will then clear its authentication state and optionally redirect the user back to a specified post-logout URL.
Endpoint
The endpoint is advertised in the end_session_endpoint in the metadata exposed by the discovery endpoint and typically is:
GET https://[BASE_URL]/connect/endsession
Parameters
Parameter
Required
Description
id_token_hint
Recommended
The ID Token previously issued by the IdP. Helps the IdP identify the RP and user session to sign out.
post_logout_redirect_uri
Optional
URL to which the IdP should redirect the user after logout. Must be pre-registered with the IdP.
state
Optional
Opaque value used by the RP to maintain state between the logout request and response. Returned to the RP in the redirect.
Usage
Obtain id_token_hint:
When the RP authenticates the user via the Authorization Endpoint, it receives an ID Token. This token is typically passed as the id_token_hint when initiating logout.
Redirect the User to Logout Endpoint:
Example redirect:
The CIBA Endpoint allows a client to initiate an authentication request without redirecting the user’s browser. Instead, authentication is performed out-of-band on a separate device or channel (e.g., a mobile app, push notification, or secure device).
CIBA is particularly suited for:
Decoupled authentication flows
Devices without browsers (e.g., smart devices, kiosks)
High-assurance or step-up authentication scenarios
Client polls the Token Endpoint until authentication completes. Do not poll more often than indicated in the response for the CIBA request.
Ping
Yes
Authway notifies client when authentication is complete. The standard still allows the client to also Poll, but it is better to wait for the notification.
Push
No
Tokens are pushed directly to the client.
Endpoint
The endpoint is advertised in the backchannel_authentication_endpoint in the metadata exposed by the discovery endpoint and typically is:
GET https://[BASE_URL]/connect/ciba
Parameters
Parameter
Required
Description
client_id
Yes
The client identifier registered with the IdP.
scope
Yes
Space-delimited list of scopes. Must include openid.
acr_values
No
Space seperated string with special requests from the client. See below.
login_hint
Conditional
Hint identifying the end user (unique identifier, username, email, social security number). If it is not the unique identifier it is recommended to also pass the tenant or the authentication might fail.
Message displayed to the user during authentication for request correlation.
requested_expiry
No
Desired lifetime (in seconds) of the authentication request. Can only shorten the lifetime configured on the client or in Authway.
request
No
Instead of providing all parameters as individual parameters, it is possible to provide a subset or all them as a JWT.
request_uri
No
URL of a pre-packaged JWT containing request parameters.
ui_locales
No
End-User’s preferred languages, represented as a space-separated list of language tag values, ordered by preference. For instance, the value “sv-SE en” represents a preference for Swedish as spoken in Sweden, then English (without a region designation).
Note Exactly one of login_hint, login_hint_token, or id_token_hint must be provided to identify the user.
acr_values parameters
The acr_values parameters are passed as “parameter:value” and if multiple parameters are passed they should be seperated with a space. For example:
Text displayed to the user during the authentication. Passed on to BankId without modification.
bankid_user_visible_data_format
No
The format of the text in binding_message parameter and can be plaintext (default) or simpleMarkdownV1. Passed on to BankId without modification.
bankid_call_initiator
No
Indicates if the user or your organization initiated the phone call (so only handled during a CIBA request). Valid values are user (default) or RP. Passed on to BankId without modification.
Usage
Client Initiates Backchannel Authentication:
The client builds a CIBA request and post it to the IdP:
The user is notified or instructed somehow what to do. Excatly how this is done can vary depending on scenario and mechanism for authenticating the user.
User will approve or deny the request.
Client Retrieves Result (Token Endpoint)
The client polls (or is notified depending on mode) and exchanges auth_req_id at the Token Endpoint:
HTTP POST /connect/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)
grant_type=urn:openid:params:grant-type:ciba&
auth_req_id=1c266114-a1be-4252-8ad1-04986c5b9ac1
There are more details in the Token Endpoint documentation.
Security Considerations
binding_message helps users detect phishing or unsolicited requests.
Authentication requests are short-lived and one-time use.
Rate-limit polling to respect the interval value.
Related Endpoints
Token Endpoint – To retrieve tokens after authentication.
The scope introspection is a custom endpoint that Authway supports.
Tokens (both ID token and access token) can become large when they contain many claims and there are good reasons for keeping them small. For access tokens one solution is to use reference token.
Another challenge with tokens is that their content often is static after the creation. This can become a problem especially for long-lived tokens. For user permissions this is often not desirableand the change must take effect before the lifetime of the token has expired.
Authway therefor exposes the scope introspection endpoint that allows an API (or client) to fetch both updated and new claims from the IdP.
Endpoint
The endpoint is advertised in the scope_introspection_endpoint in the metadata exposed by the discovery endpoint and typically is:
GET https://[BASE_URL]/connect/scope/introspect
Parameters (form-encoded)
Parameter
Required
Description
sub
Yes
The unique identity of the user sub.
scope
Optional
Space-delimited list of scopes. If not passed Authway will return claims for the perms scope. Only identity scopes are allowed and not API scopes.
tid
Optional
The unique identity of the tenant.
Authentication
The API (or client) must authenticate (e.g., Basic Auth or in the body, with Api resource and api_resource_secret or client_id and client_secret).
Response
A successful response is a JSON object containing user claims. Example: