OpenID Connect APIs

The OpenID Connect APIs include the following endpoints, all of which are discussed in detail in this documentation:

  • ​/{customer_id}/login/authorize. Requests an authorization code from the authorization endpoint.
  • ​/{customer_id}/login/token. Exchanges an authorization code or a refresh token for a set of Hosted Login tokens.
  • /{customer_id}/profiles/oidc/userinfo. Retrieves user profile information from the userinfo endpoint.
  • /{customer_id}/login/.well-known/openid-configuration. Retrieves configuration information from the discovery document.
  • /{customer_id}/login/jwk. Returns the JSON web keys associated with the customer ID.

/{customer_id}/login/authorize

Requests an authorization code from the authorization endpoint.

This endpoint includes the following methods:

  • GET

GET

Description

The /{customer_id}/login/authorize endpoint is used to request an authorization code from the authorization endpoint. If this call succeeds, the client will be sent an authorization code; that code can then be presented to the token endpoint and exchanged for an access token, refresh token, and identity token.

In order to receive a code:

  1. An authorization request to the authorization endpoint; this request must be made using an OIDC client associated with the endpoint.
  2. If the request is valid, the authorization endpoint uses the OIDC client’s login policy to redirect the user to the appropriate login page where he or she attempts to log on.
  3. If authentication is successful, an authorization code is returned, and the user is redirected to the location specified by the request’s redirect_uri parameter.

The /{customer_id}/login/authorize endpoint can be used with either of the following authorization flows:

  • Authorization Code for Web Apps. With this flow, the client secret of the OIDC client must be included as part of the token exchange request. For security reasons, it’s recommended that client secrets not be stored on mobile devices. Consequently, this flow type should not be used to make authorization requests from mobile devices.
  • Authorization Code + PKCE for Mobile Apps. With this flow, the client secret does not need to be included as part of the token exchange request. Instead, a code verifier, code challenge, and code challenge method are used to help ensure the validity of each request and each transaction. Because the client secret is not required, this flow is recommended for authorization requests from mobile clients.

Request Parameters

The query parameters for the /{customer_id}/login/authorize endpoint include the following:

Parameter Required Description
client_id Yes Unique identifier of the OIDC Client making the request. For example:
22c9604-7b27-464f-bff5-83ba229323af
response_type Yes Specifies the authentication and authorization flow type.
scope Yes

Indicates the scopes you are requesting access to. For example:

openid profile email

Scopes can be collections of claims, and claims (for the most part) map to individual user profile attributes. For example, the email scope consists of two claims: emailAddress and emailVerified. With OpenID Connect, the openid scope must always be requested. This tells the authorization server that you want to authenticate by using OIDC.

redirect_uri Yes
The URI (e.g., the web page) that clients are redirected to after being authenticated. For example:
https://documentation.akamai.com

The redirect_uri used in the /authorize request must exactly match a whitelisted redirect_uri for the client. Also, the redirect_uri sent in the /authorize request must be the same one that is sent in a subsequent /token request.

state No (but tecommended)
Value of the anti-forgery state token. For example:
99846266547289293014765635352342

The state is an opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie.

prompt No

Specifies the system behavior when a user needs to be reauthenticated (for example, because the max_age limit has been exceeded). Hosted Login supports two prompt values:

  • none. When a user needs to be reauthenticated, the authorization server first checks to see if the user currently has a valid Hosted Login session. If true, the user is then “silently” reauthenticated (that is, no authentication dialog box is displayed, and the user never knows he or she was reauthenticated). If false, an error is returned, and the user must reauthenticate in order for their Hosted Login session to continue.

  • login. The user is always asked to reauthenticate, regardless of whether he or not he or she currently has a valid session.

If this value is not specified then, when a user needs to be reauthenticated, the authorization server first checks to see if the user has a valid Hosted Login session. If so, the user is then “silently” reauthenticated (that is, no authentication dialog box is displayed, and the user never knows they were reauthenticated). If the user doesn’t have a valid session, he or she is prompted to reauthenticate.

max_age No Specifies the maximum amount of time (in seconds) that a logon session can last before the user is required to reauthenticate.
ui_locales No
Specifies the end user’s preferred language (or languages) for the login and registration user interfaces. Language preferences should be passed as a set of space-delimited RFC5646 language codes; for example:
"en-US en-GB fr-CA"

In the preceding example, Hosted Login will first attempt to render the UI in US English. If that fails, the UI will be rendered in British English and then, if necessary, Canadian French.

If this parameter is not present, the default language and local will be used. Note that no error will be returned if you specify an invalid language code, or if your application does not support a specified language.

code_challenge Yes (with PKCE)

Encrypted value generated by the client. This value will need to be verified before the client will be allowed to exchange an authorization code for a set of tokens.

For example:
code_challenge= RTg4QjMyRUJCNzdBRTQ1MkM2NTAzRTVDOEQ5OTg3QjIwMjVBNT
cxQTU5RT
JFNDYwMzJBQjYxRkM4NjQ0QzdBNw
code_challenge_method Yes (with PKCE)
Hashing algorithm used to generate code challenge. For example:
code_challenge_method=SHA256
nonce No (but recommended) String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token.

Authentication

No authentication is required to call the /{customer_id}/login/authorize endpoint.

Sample Request 1: Authorization Code Flow (curl)

The following command uses the Authorization Code flow to request an authorization code from the https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/authorize endpoint:
curl -X GET \
 'https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/authorize?\
client_id=21d832df-e92e-4e32-80df-8726d47992fa&redirect_uri=\
https://documentation.akamai.com/debug&scope=openid&response_type=code&state=dgwt5dbcxja'

Sample Request 2: Authorization Code + PKCE Flow (curl)

The following command uses the Authorization Code + PKCE flow to request an authorization code from the endpoint https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/authorize. To use PKCE, the code_challenge and code_challenge_method parameters were added to the previous authorization request.
curl \
 'https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/authorize?\
client_id=21d832df-e92e-4e32-80df-8726d47992fa&redirect_uri=\
https://documentation.akamai.com/debug&scope=openid&response_type=code&state=dgwt5dbcxja&\
code_challenge=RTg4QjMyRUJCNzdBRTQ1MkM2NTAzRTVDOEQ5OTg 3QjIwMjVBNTcxQTU5RTJFNDYwMzJBQjYxRkM4NjQ0QzdBNw&\
code_challenge_method=SHA256' 

Responses

200 OK

If your call to this endpoint succeeds, you'll get back a response similar to the following:
https://v1.api.us.janrain.com/00000000-0000-3000-8000-000000000000/login/code?state=security_token%
3bd5262737237ef4a %url%https://hosted-login.akamai.com/callback&code=4/JR27W91a-ofgCe9ur2m6bTghy77

Note that you will get the same response back regardless of whether you are using the Authorization Code flow or the Authorization Code + PKCE flow. When using the Authorization Code + PKCE flow, no information about the code challenge or code challenge method are included in the response.

Errors

The following table includes information about some of the errors that you could encounter when calling this endpoint.

Error Description
invalid_client The supplied OIDC client ID is not associated with the authorization endpoint. When OIDC clients are created, they must be associated with – and, as a result, can only be used with – a specific authorization endpoint.
invalid_redirect_uri The value for the request’s redirect_uri parameter does not match any of the redirect URIs specified in the OIDC client. Each OIDC client has a set of authorized redirect URIs: one of those authorized URIs must be used as the value of the redirect_uri parameter.
invalid_request

Typically indicates that a required parameter is missing from the request. When that occurs, the error description will usually tell you which parameter is missing:

scope_is_missing

unsupported_response_type Occurs if the parameter value supplied for the response_type parameter is anything other than code.

/{customer_id}/login/token

This endpoint includes the following methods:

  • POST

POST

Description

Exchanges an authorization code or a refresh token for an access token, refresh token, and identity token.

Request Parameters

The x-www-url-encoded parameters for the /{customer_id}/login/tokens endpoint include the following:

Parameter Type Required Description
grant_type string Yes

Specifies the type of authorization grant being requested. Allowed values are:

  • authorization_code. Indicates that you want to exchange an authorization code for a set of tokens.

  • refresh_token. Indicates that you want to exchange a refresh token for a new set of tokens.
code string No The authorization code being exchanged. Use this parameter if the grant_type is set to authorization_code.
refresh_token string No The refresh token being exchanged. Use this parameter if the grant_type is set to refresh_token.
code_verifier string No Required if you are using PKCE (Proof Key for Code Exchange) and your original authorization request includes the code_challenge parameter. The code_verifier must be the same verifier used to generate the initial code challenge.
redirect_uri url Yes URI of the page the user will be redirected to following the token exchange.

Authentication

This endpoint requires Basic authentication unless you are using PKCE (Proof Key for Code Exchange). With PKCE flows, no authentication is required.

When configuring authentication, use your Hosted Login OIDC client ID as the username and the OIDC client secret as the password.

Sample Request (Curl)

The following command exchanges the authorization code K2MzvxY8nIRhNQYe for a set of tokens:
curl -X POST \
  https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/token \
  -H 'Authorization: Bearer RcaWTi0woO52rqZjlbApm2lL3Aokzd1bhCZZajX51aX4IQrH1Uj1D4ks9HfJtxoRI7HCsyNVoc6Qj\
4oBfuplftc7tMbR26eZHwtEqaw9RLMBeIJDvqvqyD4l' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code=K2MzvxY8nIRhNQYe&redirect_uri=https%3A%2F%2F
documentation.akamai.com&\
code_verifier=AdleUo9ZVcn0J7HkXOdzeqN6pWrW36K3JgVRwMW8BBQazEPV3kFnHyWIZi2jt9gA'

Responses

200 OK

If your call to this endpoint succeeds, you'll get back a response that includes an access token, a refresh token, and an identity token:
{
   "access_token": "5na7KhMcUqnpoVDCRBX5na7Lwgh7L6qOaAlb1r2r_VKcemGgbh634rv261zbghfg6t",
   "refresh_token": "iTsA4i2Px4TEzBrfLIvddjnDVBJxjPDuCARHH_Xk7EzdpGq5GPQcsxCWM2SxdlwU",
   "expires_in": 3600,
   "token_type": "Bearer",
   "scope": "email openid profile",
   "id_token": "kyJhbGciOiJSUzI1NiIsImtpZCI6ImE5NjRhNjE3YTc0YjZjZWNlMDM4NTdkYWExZThlMTQ0ZDExMTMyYTkiLCJ0eXA
iOiJKV1QifQ.eyJhdF9oYXNoIjoiV1Y0STlVbjFWSi96Q25iRHVoWndIUSIsImF1ZCI6WyJhMjJjOTYwNC03YjI3LTQ2NGYtYmZmNS04M2J
hMjI5MzIzYWYiXSwiYXV0aF90aW1lIjoxNTUzMDI3MjEzLCJleHAiOjE1NTMwMzA4MzksImdsb2JhbF9zdWIiOiJjYXB0dXJlLXYxOi8vYj
I3LTQ2NGYtYmZmNS04M2JhMjI5MzIzYWYiXSwiYXV0aF90aW1lIjoxNTUzMDI3bm5qZXl6eXJydDJubTVkcmY1bmtuOC91c2VyLzc5OGQ2N
TQwLWExYTYtNDFiNS1iZjcxLTg1YjY5NDFkY2E4MCIsImlhdCI6MTU1MzAyNzIzOSwiaXNzIjoiaHR0cHM6Ly9hcGkubXVsdGkuZGV2Lm9y
LmphbnJhaW4uY29tLzAwMDAwMDAwLTAwMDAtMzAw YjI3LTQ2NGYtYmZmNS04M2JhMjI5MzIzYWYiXSwiYXV0aF90aW1lIjoxNTUzMDI3ND
FiNS1iZjcxLTg1YjY5NDFkY2E4MCJ9.TRaDP-i2_a0Z2s6MYh3LQEyTU5UkR1el6w_waPFeV2hZgv10pDHu6xVrAZUZwErU0_mSDbe9bJo5
I_yuecgXZ_4Q1WNV0Z4zhTJ-T9ycpN-eSwgPQcDGddh8J1ybI0Rg6yM54OOcf6o_shqrQMGiiFirm9Grt-P YjI3LTQ2NGYtYmZmNS04M2J
hMjI5MzIzYWYiXSwiYXV0aF90aW1lIjoxNTUzMDI319-S83qGyLStH5db06iVjFahdNex0w39uQSHlTf7Ay0Acb0JOtMOk7JUC406wT5WT5
Jz1q-GV2q_ChvxdUCCnd2Vp8lNba3AyznkehABHeISkNYtJ6BKigQ"
}

Error Codes

The following table includes information about some of the error codes that you could encounter when calling this endpoint.

Error Code Description
400

Error Message: Invalid_grant.

Typically occurs if you pass an invalid authorization code or if the authorization code has expired. Authorization codes are valid only for a few minutes.

If you encounter an error when calling this endpoint your error message will look similar to this:
{
   "error": "invalid_grant",
   "error_description": "code not found or expired"
}

/{customer_id}/profiles/oidc/userinfo

Returns user profile information from the userinfo endpoint.

This endpoint includes the following methods:

  • GET

GET

Description

Returns user profile information for from the userinfo endpoint. To use this endpoint, you must include an access token in your authorization header; in turn, that means you can only get back the scopes and claims (user attributes) assigned to the token. In addition, you can only get back claims for the user that the token was issued to. For example, if the token was issued to Karim Nafir and the token was assigned the email scope, then you can only get back the emailAddress and emailVerified claims for Karim Nafir. That’s because emailAddress and emailVerified are the only two claims in the email scope.

URI Parameters

No additional parameters are required to call the /{customer_id}/profiles/oidc/userinfo endpoint.

Authentication

This endpoint requires Bearer authentication. To use this authentication, include the word Bearer in your Authorization header, followed by the value of the access token being used to retrieve the user data. For example:
Authorization: Bearer 03v-cgrdpp69hHXXIx56pRLyD98kldDxqEwI59MFCFGVuSkLmmkzgmfwm324Wli

Sample Request (curl)

The following command returns user information for the user and scopes associated with the access token 03v-cgrdpp69hHXXIx56pRLyD98kldDxqEwI59MFCFGVuSkLmmkzgmfwm324Wli:
curl \
   https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/profiles/oidc/userinfo \
   -H 'Authorization: Bearer 03v-cgrdpp69hHXXIx56pRLyD98kldDxqEwI59MFCFGVuSkLmmkzgmfwm324Wli' \
   -H 'Content-Type: application/x-www-form-urlencoded'

Responses

200 OK

If your call to this endpoint succeeds, you'll get back the requested user profile information:
{
    "emailAddress": "karim.nafir@mail.com",
    "emailVerified": true
}

Error Codes

The following table includes information about some of the error codes that you could encounter when calling this endpoint.

Error Code Description
400

Error Message: Invalid_request

Indicates that the subject and data authority do not match.

401

Error Message: Invalid_token

Typically occurs if you pass an invalid authorization code or if the authorization code has expired. Authorization codes are valid only for a few minutes.

If you encounter an error when calling this endpoint your error message will look similar to this:

{
   "error": "invalid_request",
   "error_description": "subject and data authority host do not match"
}

/{customer_id}/login/.well-known/openid-configuration

Returns the information found in the discovery document.

This endpoint includes the following methods:

  • GET

GET

Description

Returns the discovery document, a set of OIDC values that can be retrieved by a client; using these values enables OIDC clients to configure themselves. For example, you shouldn’t have to hard-code the token URL in a client. Instead, the client can simply connect to the well-known endpoint and retrieve the token URL itself.

The discovery document is more formally referred to as the “well-known endpoint;” that’s why the string well-known appears in the endpoint URL.

URI Parameters

No parameters are required in order to call the /{customer_id}/login/.well-known/openid-configuration endpoint.

Authentication

This endpoint does not require authentication.

Sample Request (Curl)

The following command returns for discovery document for the organization with the Hosted Login customer ID 00000000-0000-0000-0000-000000000000:
curl \
  https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/.well-known/openid-configuration

Responses

200 OK

If your call to this endpoint succeeds, you'll get back the configuration values found on the discovery document:

{
    "issuer": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login",
   "authorization_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/
authorize",
   "token_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/token",
   "introspection_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/
token/introspect",
   "revocation_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/
token/revoke",
   "userinfo_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/profiles/
oidc/userinfo",
    "jwks_uri": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/jwk",
    "response_types_supported": [
        "code"
    ],
   "subject_types_supported": [
        "public"
    ],
   "id_token_signing_alg_values_supported": [
        "RS256"
    ],
   "grant_types_supported": [
       "authorization_code",
       "refresh_token"
    ],
   "token_endpoint_auth_methods_supported": [
       "client_secret_basic",
       "client_secret_post"
    ],
   "scopes_supported": [
        "openid",
        "profile",
        "email",
        "address",
        "phone"
    ],
   "claims_supported": [
        "sub",
        "iss",
       "auth_time",
        "acr",
        "name",
       "given_name",
        "address",
       "family_name",
       "middle_name",
       "preferred_username",
        "gender",
       "birthdate",
       "updated_at",
       "phone_number",
       "phone_number_verified",
        "email",
       "email_verified"
    ],
   "code_challenge_methods_supported": [
        "S256"
    
}

/{customer_id}/login/jwk

Returns information about the JSON web keys associated with the specified customer.

This endpoint includes the following methods:

  • GET

GET

Description

Returns information about the JSON web keys (JWK) associated with a customer. JSON web keys are public cryptographic keys used to verify the signatures on Hosted Login identity tokens.

URI Parameters

No parameters are required in order to call the /{customer_id}/login/jwk endpoint.

Authentication

This endpoint does not require authentication.

Sample Request (Curl)

The following command returns the JSON web keys associated with the customer ID 00000000-0000-0000-0000-000000000000:
curl -https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/jwk

Responses

200 OK

If your call to this endpoint succeeds, you'll get back a collection of JSON Web Keys similar to this:

{
    "keys": [
        {
            "use": "sig",
            "kty": "RSA",
            "kid": "51300370a8e1ac0a14a59cdd9c881d3f24c01f78",
            "alg": "RS256",
            "n": "w9OLNr_6sIuqr8OO3nPzorbv8tkmXC-m0k0O3W6gdk1QipvJ2pZkRSzD_iIWnEvYV11RuOBSAb7e_nU7mwNnxX6m
ORyJIEwnHKucBwaHQhuo56uVUjNTsRI6OuLB6REwxLM0ePPQPJNaXncWzt83oYdHU10VPmp5x0Sj-GjTvMpm2Y4I14KnFUXMEvIC-e5lf2
P7q6KMXNw3PchEvmO5fVCgXf5-FgzDzEyn0qXrerdui4lGUtzcREPFksPNLNMlqp0XL5Kz1QLLkKDtR3dVjEtViEYJ6extcI-xFEV785hO
4Ok36N99ht41EZk8ibrflNnYkJIEXAw_LKkmtxyZKw",
            "e": "AQAB"
        },
        {
            "use": "sig",
            "kty": "RSA",
            "kid": "f63eecd7318b6a6bcfae82f9607689756c6dd83e",
            "alg": "RS256",
            "n": "2kTH-jB0XDAb4yJy9rRMKNTNk4FEz7n3mbzj7nvupGvozyrpgHNFzSNW-Faxfo8v3cMdekd0-3S1ioNquAn9bbKZ
8j2D4wK7rYtJgwOE8vnHkLUPAQuv_ymUgdgRAz7iQhsUN-vs8QLIDTddzEGnKWZASndLb-CYN_3eSWCDL7J8kQGkm9EI91OY1tKUUdIxlH
pr90zAR36CFWWIJY1hpgFFnC1Po2r4nBtkBZD-SG_tmWB7fmWmF9v9MNnpmY00h3PsvUfzb6dSzLNt3H2ocSys7F5syaulRGLiKFiTalPP
ri_wAj-CPVfqiZuEys8PNTVd6T969PM4dIFdIsR0gw",
            "e": "AQAB"
        },
        {
            "use": "sig",
            "kty": "RSA",
            "kid": "a964a617a74b6cece03857daa1e8e144d11132a9",
            "alg": "RS256",
            "n": "7-LW8dGJKFsxU6ztkRA_qdhzvuHkoeWlRGL6ejqW9z_PxtDnQbLIpiy0vFm_DYAyNyFXt1EbuVMzESd4XRCKue4L
w2tGS_iiVQhlq7RkwAYG-hOkiiIHCcLVVCxtPm8gdmW-Cp4sdDozG0Yc99os-nyBtm2YzZ3ECAMsQsQVIjR03_JD3l1u79F4EzWcs2aBMO
Q0NFDHqoQyk16Gf6Ww5QMXBtFhI508kYDMg71-0cxpssOrkztBBkxH1WPDpeliEAO91Sy1HDgXkuKdEuPkB3JxUqGXiw_UAez0a4XXBMFN
kc5pV8byrKWokKmzNSgSfObqaRx13wOk5xjyVpyfHQ",
            "e": "AQAB"
        }
    ]
}