/{customer_id}/config/clients/{client_id}

The Akamai Identity Cloud supports two types of OIDC clients:

  • Confidential clients. Clients capable of securely maintaining a client secret; this secret is then used when the client is employed to help manage user logins and registrations. Confidential 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 for managing for 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 logon policy and are not associated with an application client. If your API response includes a confidential client that is not associated with a login policy or an application client, that’s a configuration client.

  • Public clients. Clients (such as native mobile apps and single page apps) not capable of keeping a secret confidential. Because of that, public clients must use PKCE (Proof Key for Code Exchange) when assisting with user logins and registrations. Public clients can only be used by end-user facing applications.


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 /{customer_id}}/login/token endpoint. The access token returned from the /{customer_id}}/login/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.


Methods

This endpoint supports the following methods:

 

GET

Description

Returns information about the specified OpenID Connect (OIDC) client. Keep in mind that, when returning information for a confidential client, the client secret will not be returned: at this point in time there is no way to access a confidential client secret after the fact. If you forget your client secret (or if you have reason to change a client secret), you can do so by using the /secret endpoint.


Path Parameters

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

Name Type Required Description

{customer_id}

string

Yes

Unique identifier of the customer associated with the OIDC client.

{client_id}

string

Yes

Unique identifier of the OIDC client to be returned.


Sample Request (Curl)

The following command returns information about the OIDC client with the client ID 6be73a3a-5bf0-4190-a0de-698aa409ff28:


curl -X GET \
  https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/clients/6be73a3a-5bf0-4190-a0de-698aa409ff28 \
  -H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB'


Responses

200 OK

If your call to this endpoint succeeds, you'll get back detailed information for the specified OIDC client:

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


Response Codes

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

Response Code Description

400

Bad request. Typically a syntax error: you might have left off a parameter or misspelled the parameter name. 

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.

404

Customer client not found. Either you specified an invalid client (use the/config/{customer_id}/clients endpoint to retrieve a list of valid client IDs) or the OIDC client has been deleted.

409

Dependency error

 


PUT

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.


Path Parameters

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

Name Type Required Description

{customer_id}

string

Yes

Unique identifier of the customer associated with the OIDC client.

{client_id}

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:

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

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. If you want to convert an existing confidential client into a configuration client then omit 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 value for refresh tokens.

For example:

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

tokenPolicy is a required property regardless of whether you are working with a confidential client, a public client, or a configuration client.

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). However, you can convert a confidential client into a configuration client by omitting the loginPolicy parameter. If you do that, you will also need to assign a new token policy to the client.

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

The one exception to this rule is the loginPolicy; no error will be generated if you leave out this key. If you do so, however, two things will happen:

  • The loginPolicy key will be deleted. That means that the OIDC client will no longer have an assigned login policy.
  • The application client associated with the OIDC client will be deleted.

The net result? If the login policy is deleted (and the application client removed), then the OIDC client can no longer be used for logins and registrations. However, the client can still function as a configuration client.


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 Code Description

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

 


Delete

Description

Deletes the specified OpenID Connect (OIDC) client. 

Deleting an OIDC client only deletes the client itself and the associated application (API) client. The associated login policy and token policy are not affected when a client is deleted.


Path Parameters

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

Name Type Required Description

{customer_id}

string

Yes

Unique identifier of the customer associated with the OIDC client.

{client_id}

string

Yes

Unique identifier of the OIDC client being deleted.


Sample Request (Curl)

The following command deletes the OIDC client with the client ID 6be73a3a-5bf0-4190-a0de-698aa409ff28:


curl -X DELETE \
  https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/config/clients/6be73a3a-5bf0-4190-a0de-698aa409ff28 \
  -H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB'


Responses

204 No Content

If your call to this endpoint succeeds, you will not get back a response value. Instead, you will simply get back the HTTP response code 204 No Content.


Response Codes

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

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.

404

Customer client not found. Either you specified an invalid client (use the /{customer_id}/config/clients endpoint to retrieve a list of valid client IDs) or the OIDC client has been deleted.