The OpenID Connect Discovery Document

Also referred to as the "well-known endpoint," the discovery document is a set of OpenID Connect values that can be retrieved by OIDC clients; it’s the discovery document that enables OIDC clients to configure themselves in order to be able to access your implementation of Hosted Login. A client that connects to your discovery document can easily do such things as: 

  • Identify the claims and grant types that you support.
  • Retrieve the URLs of your introspection server and your JSON Web Keys.
  • Determine which PKCE (Proof Key for Code Exchange) challenge methods you support.

Best of all, this can be done automatically, without requiring anyone to configure these values into the client.

As if that wasn’t enough, OIDC clients can also find discovery documents on their own. Your well-known endpoint can always be reached by adding the string value /.well-known/openid-configuration to the end of your Hosted Login issuer URI. For example, if your issuer URL is then your well-known endpoint will be found here:

Note. Your issuer URL (as well as the other URLs included on your discovery document) are generated for you by Akamai. By default, that URL includes the default Hosted Login URL ( plus your unique customer ID (for example, 00000000-0000-0000-0000-000000000000). If you prefer, however, you can use a custom issuer URL similar to this:

For more information on using a custom domain name for Hosted Login, contact your Akamai representative.

You can access the discovery document page simply by entering the URL for the well-known endpoint or by using an API call to return discovery document values in JSON format. For example, here’s a Curl command for returning the discovery document:

curl \

Regardless of the method you choose, here’s the sort of information you’ll get back in return

    "issuer": "",
    "authorization_endpoint": "",
    "token_endpoint": "",
    "introspection_endpoint": "",
    "revocation_endpoint": "",
    "userinfo_endpoint": "",
    "jwks_uri": "",
    "response_types_supported": [
    "subject_types_supported": [
   "id_token_signing_alg_values_supported": [
    "grant_types_supported": [
   "token_endpoint_auth_methods_supported": [
    "scopes_supported": [
    "claims_supported": [
   "code_challenge_methods_supported": [

We thought someone might ask that: what do things like code_challenge_methods_supported  and id_token_signing_alg_values_supported actually mean?  To help answer those questions, the following is a list of the endpoints and configuration settings included on the typical Hosted Login discovery document.

Important. All organizations that subscribe to Hosted Login get the same discovery document (except, of course, for their endpoint URLs). This is true even if you specify custom claims in one of your token policies. The discovery document only lists the standard claims supported by Hosted Login; it will not list any custom claims you define elsewhere.

Hosted Login Endpoints

Back to top


The base URL for your Hosted Login implementation. And here’s a tip: any time you see the  iss claim in a token, the value of that claim will be the issuer URL.


Endpoint that validates all authorization requests. If a request is valid (for example, if it includes an authorized OIDC client, among other requirements) the user is then redirected to the login page. At the login page, the user logs on and, if successfully authenticated, is given an authorization code that can be exchanged for an access token. The latter exchange takes place at the token endpoint.


URL of the token endpoint. After a client has received an authorization code, that code is presented to the token endpoint and exchanged for an identity token, an access token, and a refresh token.


URL of the authorization server’s introspection endpoint. By default, access tokens and refresh tokens are “opaque” to clients. For example, a typical access token looks like this:


Although that looks fairly simple (albeit extremely unreadable), an access is actually accompanied by a large amount of metadata that specifies everything from when the token expires to the scopes that the token holder should have access to. That’s good, except that resource servers are typically not equipped to decipher tokens and to retrieve this metadata; instead, resource servers usually contact the introspection endpoint to determine whether a token is valid and whether access to a specific resource should be granted. 


URL of the revocation endpoint, the endpoint used to revoke access or refresh tokens issued by the authorization server. After a token has been revoked it can no longer be used: access tokens can no longer be presented when a user requests access to a resource, and refresh tokens can no longer be used to request new access tokens.

The revocation endpoint enables clients to do such things as invalidate tokens any time a user logs out or any time a user uninstalls the application that requested the token.  Invalidating tokens helps minimize the problems that surround “abandoned” tokens: tokens that are still valid but that the user is unaware of. If tokens are deleted at logoff time you reduce the chances of a valid token somehow falling into malicious hands.


URL of the user info endpoint, which returns user profile information to a client. Keep in mind that the user info endpoint returns only the information that has been requested: if you only request the user’s email address you will not get back their telephone number as well. In addition, and depending on how your system has been configured, the endpoint will only return information that the user has given consent to make available to specific requests.

Currently the user info endpoint is the only protected resource managed by Hosted Login.


URL of your JSON Web Key Set. This set is a collection of JSON Web Keys, a standard method for representing cryptographic keys in a JSON structure. For Hosted Login, that collection consists of the public keys used to verify the signatures of the identity tokens issued by the authorization server.

Configuration Settings

Back to top


Specifies the way the authorization server responds after a user successfully authenticates. For its initial release, Hosted Login only supports the code response type: after a successful login, the user is given an authorization code. That code can then be exchanged for an access token, a refresh token, and an identity token.


JSON array containing a list of the supported Subject Identifier types. Currently Hosted Login only supports the public type, in which a user (subject) is issued a single unique identifier (the Akamai Identity Cloud UUID). The user then employs this identity on all of your clients; among other things, this enables you to easily keep track of users regardless of which client they might be using.


JSON array consisting of all the JSON Web Signature algorithms that can be used for signing JSON Web Tokens. Hosted Login supports currently one signing algorithm: RS256


Specifies the different ways that a client can be granted an access token and, as a result, can be given access to specific resources. Hosted Login supports two grant types:

  • authorization_code– After authentication, the client is given an authorization code. That code can then be exchanged for an access token.
  • refresh_token– Before an access token expires (by default, access tokens are only valid for one hour), a refresh token can be used to obtain a new access token.


JSON array containing a list of client authentication methods supported by the token endpoint. Hosted Login supports the following authentication methods: 

  • client_secret_post– Authentication method in which the client sends authentication information as part of the request body in an HTTP POST.
  • client_secret_basic– Authentication method which employs the HTTP Basic Authentication Scheme. In this scheme (which should only be used on a secure connection), the client passes a user ID and password to the server as part of an Authorization header.


JSON array containing a list of the scopes that the authorization server supports. Scopes are a collection of claims (for Hosted Login, each claim typically represents one piece of user information, such as the user’s first name or cell phone number). For example, you could request the following individual claims from a user profile:

  • name
  • given_name
  • family_name
  • middle_name
  • preferred_username
  • gender
  • birthdate
  • updated_at

Alternatively, you could request the profile scope, which includes each of the preceding claims.

Hosted Login does not support the ability to create custom scopes.


A list of the claims supported by this authorization server. For Hosted Login, each claim represents one piece of user information, such as the user’s first name or cell phone number. In addition to the default claims, Hosted Login supports the ability to collect custom claims; see Scopes and Claims for more information.


JSON array containing a list of Proof Key for Code Exchange (PKCE) code challenge methods supported by this authorization server. With PKCE, a client cannot request authentication until it creates a unique string value (the code_verifier), which is hashed to create a code_challenge. The code_challenge and hashing algorithm are then sent to the authorization server along with the request for authentication.

Assuming the user authenticates successfully, the server sends an authorization code to the client and retains the code_challenge and hashing method associated with that code. When the client tries to exchange the authorization code for an access token, that client must also present the code_verifier. The server then uses the verifier and the hashing method to recreate the code_challenge. If the recreated value does not match the value of the code_challenge sent as part of the authorization request the request for an access token will be denied.

Note. Got all that? If not see, the article Authorization Code + PKCE for more information. 

Hosted Login only supports the S256 code challenge method (also referred to as the SHA-256 or Secure Hash Algorithm).