Modify an OpenID Connect Client

Endpoint URL: {identityDomain}/{customerId}config/clients/{oidcClientId}


Description

Modifies the specified OpenID Connect (OIDC) client. When modifying OIDC clients remember that:

  • You cannot modify an OIDC client’s client secret by using the PUT method. If you need to change a client secret, use the /secret endpoint instead.
  • You cannot change the client type: once a public client always a public client.

Video: Adding a Redirect URI


Respects the API Client Allow List: No


Authentication

This endpoint requires token-based authentication. To obtain an access token, you must use a configuration client (using the client ID as the username and the client secret as the password) to access the /{customerId}/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 would 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.

Path Parameters

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

NameTypeRequiredDescription

{customerId}

string

Yes

Unique identifier of the customer associated with the OIDC client.

{oidcClientId}

string

Yes

Unique identifier of the OIDC client being modified.


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",
    "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:

KeyDescription

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 Client"

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 Client.

Incidentally, changing your the name of an OIDC client also changes the value of the site_name setting found in the associated application client. See this article for more information about what that means, and what you might want to do about that.

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: 1) provide the exact path to the Capture domain and the user profile entity type; 2) specify the allowed OAuth scopes; and, 3) 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. Login policies are not required for configuration clients. However, after a login policy has been assigned to a client that client must always have a login policy: the only way to remove a login policy assigned to a client is to assign that client a new policy.

See this article for more information.

tokenPolicy

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

For example:

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

All OIDC clients must be assigned a token policy. The only way to "remove" a token policy from a client is to assign that client a different policy.

type

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

  • confidential
  • public

Although the type parameter is required in your API call, you cannot change the client type (e.g., you can’t convert a confidential client into a public client or vice-versa). 

You must include all the keys and key values in your body request, even if those values are not being changed. For example, suppose you leave out the key value redirectURIs. In that case, your API call will fail with a 400 Bad Request error and the following error message:

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


Sample Request (Curl)

The following command changes the name of the OIDC client with the client ID 6be73a3a-5bf0-4190-a0de-698aa409ff28. Although only the name is being changed, all the other keys and key values (such as tokenPolicy) must be included in the body parameter:

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


Responses

200 OK

If your call to this endpoint succeeds, you'll get back updated information for the newly-modified OIDC client:

{
    "id": "6be73a3a-5bf0-4190-a0de-698aa409ff28",
    "name": "Akamai Training Login Client",
    "redirectURIs": ["https://localhost"],
    "loginPolicy": "b8097975-93c7-46db-8cfe-19609e67eadb",
    "tokenPolicy": "2dcae965-0d56-4961-a98e-f98583e30bb9",
    "type": "public",
    "_links": {
        "self": {
            "href": "/config/01000000-0000-3000-9000-000000000000/clients/6be73a3a-5bf0-4190-a0de-698aa409ff28"
        }
    }
}


Responses

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

Response CodeDescription

204

No content. The customer client has been updated successfully but no content is available.


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