/{customer_id}/config/clients

The Akamai Identity Cloud supports two types of OIDC clients:

  • Confidential clients. Clients capable of securely maintaining a client secret: confidential clients require that secret when authenticating with the token endpoint. These clients can be used by both end-user facing applications and machine-to-machine applications.

    The Identity Cloud also supports configuration clients. Like confidential clients, configuration clients have a client secret. However, configuration clients are not employed to help manage user logins and registrations; instead, these clients are used to acquire access tokens needed to call other OpenID Connect configuration endpoints. Because they aren’t used for logins and registrations, configuration clients are not assigned a login policy and are not associated with an application client. If your API response includes a confidential client that doesn’t have a login policy or an application client, that’s a configuration client.

  • Public clients. Clients (such as native mobile apps and single page apps) that are not capable of securely maintaining a client secret; as a result, public clients don’t have client secrets. Instead, public clients use PKCE (Proof Key for Code Exchange) to authenticate with the token endpoint. Public clients can only be utilized by end-user facing applications.
Authentication

This endpoint requires token-based authentication. To obtain an access token, you must use a confidential client (using the client ID as the username and the client secret as the password) to access the /{customer_id}}/login/token endpoint. The access token returned from the token endpoint is then used in the Authorization header of your API call. For example, if you get back the access token Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB then your Authorization header will look like this when using Curl:

-H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB'

In Postman, set the Authorization Type to Bearer and use the access token as the value of the Token field.

Methods

This endpoint supports the following methods:

  • GET
  • POST
GET

Description

Returns information about all the OpenID Connect (OIDC) clients associated with a customer, including public clients, confidential clients, and configuration clients.

Path Parameters

Path parameters that must be included in the request are listed in the following table:

Path Parameters
Parameter Type Required Description

{customer_id}

string

Yes

Unique identifier of the customer associated with the OIDC clients. Note that any one customer can have multiple OIDC clients.

Sample Request (Curl)

The following command returns information about all the OIDC clients associated with the customer 01000000-0000-3000-9000-000000000000:

curl -X GET \
  https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/clients \
  -H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB' \
  -H 'Content-Type: application/json'

Responses

200 OK

If your call to this endpoint succeeds, you'll get back information about all the OIDC clients associated with the specified customer:

{
    "total": 2,
    "_embedded": {
        "clients": [
            {
                "id": "b83fff95-a685-49db-a019-84d03275f7a0",
                "name": "Akamai Documentation Login Client",
                "_links": {
                    "self": {
                        "href": "/01000000-0000-3000-9000-000000000000/config/clients/b83fff95-a685-49db-a019-84d03275f7a0"
                    }
                }
            },
            {
                "id": "d4266439-dbb1-46ab-8976-1d192325b828",
                "name": "Akamai Training Login Client",
                "_links": {
                    "self": {
                        "href": "01000000-0000-3000-9000-000000000000//config/clients/d4266439-dbb1-46ab-8976-1d192325b828"
                    }
                }
            }
        ]
    }
}

Response Codes

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

Response Codes
Response Code Description

401

Authentication required or Invalid credentials. You either did not specify an authentication method for the call (this endpoint requires token-based authentication) or the token was rejected. In the latter case, this could be because the token is not valid or because the token has expired.

403

Forbidden. You do not have permission to access the requested resource.

POST

Description

Creates a new OpenID Connect (OIDC) client. If you include a logon policy in your API call, the POST method creates a new OpenID Connect client and associates that client with an application client (also known as an “API client”). The application client (which is automatically assigned the login_client feature) helps ensure that eventing information (such as user logins and registrations) is properly captured; the application client also maintains configuration information for the user login/registration experience, including such things as the flow name and version number, and links to CSS stylesheets and favicons. You can identify the API client associated with an OIDC client by looking for application_client in the API response:

"application_client": {
"href": "/config/kfcmdfudasmx9wkay7463vpdsy/clients/epmpqfvueuayedxynna86v9byzph44d9"
}

In the preceding example, the application client has the client ID epmpqfvueuayedxynna86v9byzph44d9 and is associated with the application kfcmdfudasmx9wkay7463vpdsy.

If you don’t include a logon policy the PUT method creates a configuration client. Configuration clients are not used for logins and registrations; instead they’re used to obtain access tokens that enable you to call OpenID Connect configuration endpoints (including this endpoint).

Path Parameters

Path parameters that must be included in the request are listed in the following table:

Path Parameters
Parameter Type Required Description

{customer_id}

string

Yes

Unique identifier of the customer associated with the new OIDC client.

Request Parameters

Request parameters for this endpoint must be formatted as a JSON object and included in the body parameter of your API call. For example:

{
    "name": "Akamai Documentation Login Client",
    "redirectURIs": ["https://localhost"]
    "loginPolicy": "b8097975-93c7-46db-8cfe-19609e67eadb",
    "tokenPolicy": "2dcae965-0d56-4961-a98e-f98583e30bb9",
    "type": "public"
}

The keys and key values used in the body parameter include the following:

Keys and Key Values
Key Description

name

Friendly name to be assigned to the OIDC client. The OIDC client name also serves as the title for the Hosted Login login page.

For example:

"name": "Akamai Documentation Login"

Incidentally, client names must be unique for each organization (i.e., for each customer ID). If your customer ID is 01000000-0000-3000-9000-000000000000 you can have only one OIDC client named Akamai Documentation Login.

redirectURIs

URL of the page the user is redirected to following authentication. The redirect URI accepts both HTTPS links and mobile deep links; however, the only allowed HTTP link is localhost:

"redirectURIs": ["http://localhost"]‘

As the name implies, you can specify multiple redirect URIs; just include each URI in double quotes and separate the URIs by using commas:

"redirectURIs": ["http://localhost", "https://documentation.akamai.com"]

When requesting authentication (or when exchanging an authorization code for a set of tokens), that request must include one of the URIs specified in the redirectURIs key. If it doesn’t, your request will fail.

Note that your redirect URI can contain any query parameters except for code and state.

loginPolicy

Unique identifier of the login policy associated with the client. Login policies do such things as: 1provide the exact path to the Capture domain and the user profile entity type, and point the user to the appropriate login page.

For example:

"loginPolicy": "b8097975-93c7-46db-8cfe-19609e67eadb"

Login policies are required for both public clients and confidential clients: you can’t login or register using an OIDC client that hasn’t been assigned a login policy. To create a configuration client, leave out the loginPolicy parameter.

tokenPolicy

Unique identifier of the token policy associated with the client. Token policies are primarily used to specify the time-to-live values for access and refresh tokens.

For example:

"tokenPolicy": "2dcae965-0d56-4961-a98e-f98583e30bb9"

tokenPolicy is a required property, and must be included in your API call regardless of whether you are creating a confidential client, a public client, or a configuration client.

type

Specifies the type of OIDC client being created. Allowed values are:

  • confidential
  • public

For example:

"type": "confidential"

Note that you cannot change the client type after it has been assigned. However, you can convert a confidential client into a configuration client by removing the assigned login policy.

In addition, note that there is no specific option for creating configuration clients. To create a configuration client, set the type to confidential and omit the loginPolicy parameter.

You must include all the preceding keys (except for loginPolicy) in your request body or your API call will fail. For example, if you leave out the type key, your call will fail with the following error message:

{
  "errors": "('type',) field required"
}

Sample Request (Curl)

The following command creates a new OIDC client (Akamai Documentation Login Client) for the customer 01000000-0000-3000-9000-000000000000:

curl -X POST \
  https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/clients \
  -H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Akamai Documentation Login Client",
    "redirectURIs": ["https://localhost"],
    "loginPolicy": "b8097975-93c7-46db-8cfe-19609e67eadb",
    "tokenPolicy": "2dcae965-0d56-4961-a98e-f98583e30bb9",
    "type": "confidential"
}'

Responses

201 Created

If your call to this endpoint succeeds, you'll get back slightly-different information depending on the type of client you created:

  • If you created a public client, you’ll get back an API response similar to the following:
    {
       "id": "9e7f2429-496d-4437-b516-048472613cf9",
       "name": "Hosted Login OIDC Client",
       "redirectURIs": [
           "https://localhost/test"
       ],
       "loginPolicy": "b8097975-93c7-46db-8cfe-19609e67eadb",
       "tokenPolicy": "48e04957-2d89-414e-bfcd-5ca6298a2f07",
       "type": "public",
       "_links": {
           "self": {
               "href": "/01000000-0000-3000-9000-000000000000/config/clients/9e7f2429-496d-4437-b516-048472613cf9"
           },
           "application_client": {
               "href": "/config/kfcmdfudasmx9wkay7463vpdsy/clients/efukr44zncxxg5hcq8njm5rnhbjpr6yf"
           }
       }
    
  • If you created a confidential client, the API response will look similar to this; note the client secret at the bottom of the response:
    {
       "id": "af4f70a3-0364-4505-94c4-8d26df86e161",
       "name": "Confidential Sample Client",
       "redirectURIs": [
           "https://oidcdebugger.com/debug"
       ],
       "loginPolicy": "b8097975-93c7-46db-8cfe-19609e67eadb",
       "tokenPolicy": "002a99a8-f890-4fe0-baa4-e5112b9e3b40",
       "type": "confidential",
       "_links": {
           "self": {
               "href": "/01000000-0000-3000-9000-000000000000/config/clients/af4f70a3-0364-4505-94c4-8d26df86e161"
           },
           "application_client": {
               "href": "/config/kfcmdfudasmx9wkay7463vpdsy/clients/epmpqfvueuayedxynna86v9byzph44d9"
           }
        "secret": "07s78-JcHxgQyylNpcvjbwOlXQJrlxT8opScTyQY5mVyPjzhy3CGbKKh6ekzK70GnqavSoc4AiwpJ6GyWZaopQ"
       }
    }
    

Keep in mind that no client secret was returned when you created a public client. Client secrets are not returned with public clients for one simple reason: public clients don’t have client secrets.

Be sure and make a copy of the client secret and store that information in a secure location. The API response marks the only time you will have access to the client secret. (As needed, however, you can use the /secret endpoint to change the password for an OIDC client.)

Response Codes

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

Response Codes
Response Code Description

400

Bad request. Typically indicates a syntax error; for example: you might have left off a parameter or misspelled a parameter name. Often-times the error description will help you pinpoint the problem; for example:

{
    "errors": {
        "tokenPolicy": [
            "Missing data for required field."
        ]
    }
}

401

Authentication required or Invalid credentials. You either did not specify an authentication method for the call (this endpoint requires token-based authentication) or the token was rejected. In the latter case, this could be because the token is not valid or because the token has expired.

403

Forbidden. You do not have permission to access the requested resource.

409

Dependency error