Web Clients API

This allows the creation of new Web clients via a REST API. It can be utilized in scripts to add many clients at once, edit or delete them.

All endpoints are protected via basic authentication, using the API client credentials. It requires an API client with the scope onegini_api_config (Config API).

Endpoints

List of Clients

This returns a list of all Web Clients.

  • Endpoint: /api/v1/configuration/web-clients
  • Method: GET

Request parameters:

Param Required Description
page no Results are limited to 100 entries. Page number defaults to 0.

Example request:

GET /api/v1/configuration/web-clients HTTP/1.1
Host: onegini.example.com

Example success response:

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
   "result":[
      {
         "name":"web client 1",
         "client_id":"365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B",
         "grant_types":[
            "AUTHORIZATION_CODE",
            "IMPLICIT"
         ],
         "redirect_url":"https://example.com/redirect",
         "additional_redirect_urls":[
            "https://example.com/redirect",
            "https://example.net/redirect"
         ],
         "access_grant_expires_in":30,
         "access_token_expires_in":3600,
         "refresh_token_enabled":true,
         "simultaneous_sessions_allowed":true,
         "max_simultaneous_sessions":25,
         "default_scopes":[
            "address",
            "email"
         ],
         "additional_scopes":[
            "phone"
         ],
         "identity_provider_id":"123-123",
         "additional_identity_provider_ids":["123-124", "123-125"],
         "logo_uri":"",
         "additional_authenticator_type":"SMS_CHALLENGE",
         "template_set":"template1",
         "consent_disabled":true
      }, 
      {
        ... more clients ...
      }
   ]
}

In the event of an error, one of the generic error codes will be returned.

Create Web Client

This creates a Web Client from scratch

  • Endpoint: /api/v1/configuration/web-clients
  • Method: POST

JSON body parameters:

Param Required Example Description
name yes "myWebClient" Custom client name
client_id yes "F167433E63CE8BD874D7…" Unique Identifier for a client
client_secret yes "AF33E2BF29C54A4639AB…" Client Secret (not returned on GET)
grant_types yes ["CLIENT_CREDENTIALS"] Set of Grant Types. Allowed values: AUTHORIZATION_CODE, CLIENT_CREDENTIALS, IMPLICIT, RESOURCE_OWNER_CREDENTIALS.
redirect_url yes "https://example.com/redirect" An URL to which the browser is redirected after successfully obtaining an Access grant. Required for Grant types AUTHORIZATION_CODE and IMPLICIT.
additional_​redirect_​urls no ["https://example.org/redirect"] Additional URLs that the user can be redirected to after successfully obtaining an Access grant.
access_​grant_​expires_​in yes 30 The number of seconds that an Access grant is valid. Required for Grant type AUTHORIZATION_CODE.
access_​token_​expires_​in yes 900 The number of seconds that an Access token is valid. Required for Grant types AUTHORIZATION_CODE, CLIENT_CREDENTIALS and IMPLICIT.
refresh_​token_​enabled no true Issue refresh tokens
simultaneous_​sessions_​allowed no true Allow users to establish multiple sessions at the same time
max_​simultaneous_​sessions no 25 Limits the number of sessions when simultaneous sessions are allowed. Value must be between 2 and 25 (inclusive). Defaults to 25 when omitted and simultaneous_sessions_allowed is true.
default_scopes no ["profile"] Default scopes are the Scopes that are automatically assigned if a Client does not request any Scopes. If you want an Authorization request to fail when no Scopes are requested, leave this empty.
additional_scopes no ["address", "email"] Additional Scopes that can be requested by a Client during an Authorization request. The Default scopes can also be requested by a Client during the Authorization request.
identity_​provider_​id no "123-123" The Identifier of an existing Identity Provider you wish to be the primary/default for this client. If none is specified in the request, this will be used.
additional_​identity_​provider_​ids no ["123-124", "123-125"] Identifiers of additional existing Identity Providers that are able to be specified in the request.
logo_uri no "https://example.com/logo.png" The URL that refers to the logo of the client.
additional_​authenticator_​type no "SMS_CHALLENGE" You can specify Additional Authenticator types to give the user a choice when registering. Allowed values: "SMS_CHALLENGE".
template_set no "template1" Identifier of an existing Template Set
consent_disabled no false When Consent is skipped, the user is not asked for Consent in the Authorization flow. The value must be true when grant_types contains PASSWORD.
open_id_connect no See table below JSON Object for OpenID Connect configuration. Required when default_scopes or additional_scopes contain openid.

The following parameters are a part of the open_id_connect object.

Param Required Example Description
expiration_​time_​seconds depends 3600 The number of seconds that an ID Token is valid. It is used to calculate the exp expiration date claim in the ID Token. Required when default_scopes or additional_scopes contains openid.
additional_​audiences no ["https://resource.example.com"] An array of case sensitive strings that identifies who is the audience of the issued ID Token. It is used to populate aud claim in the ID Token in combination with the client_id which is always included.
post_​logout_​redirect_​url no "https://redirect.example.com" This is Primary/Default Post Logout URL. The user will be redirected to this URL if no other URL is specified in the end session request.
additional_​post_​logout_​redirect_​urls no ["https://redirect.example.com", "https://postlogout.example.com"] An array of additional Post Logout Redirect URLs. This array contains the potential URLs that could be specified to be redirected to as part of the end session request.
front_​channel_​logout_​url no "https://front-channel-logout.example.com" A URL reachable on the Relying Party that will invalidate the session. This will be triggered after a successful logout via the end session page.

Example request:

POST /api/v1/configuration/web-clients HTTP/1.1
Host: onegini.example.com
Content-Type: application/json
{
  "name": "web client 1",
  "client_id": "365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B",
  "client_secret": "919724DAE12CAB220407C34EDAE8438CEAE965CD0F8AD033A743C1F4BB4B15C4",
  "grant_types": [
    "AUTHORIZATION_CODE",
    "CLIENT_CREDENTIALS"
  ],
  "redirect_url": "https://example.com/redirect",
  "additional_redirect_urls": [
    "https://example.org/redirect",
    "https://example.net/redirect"
  ],
  "access_grant_expires_in": 30,
  "access_token_expires_in": 3600,
  "refresh_token_enabled": true,
  "simultaneous_sessions_allowed": true,
  "max_simultaneous_sessions": 25,
  "default_scopes": [
    "address",
    "email"
  ],
  "additional_scopes": [
    "phone",
    "openid"
  ],
  "identity_provider_id": "123-123",
  "consent_disabled": true,
  "open_id_connect": {
    "expiration_time_seconds": 3600,
    "post_logout_redirect_url": "https://redirect.example.com"
  }
}

Example success response:

HTTP/1.1 201 CREATED
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

The success response body is empty.

In the event of an error, one of the generic error codes will be returned.

Read Web Client

This returns one Web Client.

  • Endpoint: /api/v1/configuration/web-clients/{client_id}
  • Method: GET

Path parameters:

Param Required Description
client_id yes Unique identifier of the Web Client.

Example request:

GET /api/v1/configuration/web-clients/365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B HTTP/1.1
Host: onegini.example.com

Example success response:

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
   "name":"web client 1",
   "client_id":"365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B",
   "grant_types":[
      "AUTHORIZATION_CODE",
      "IMPLICIT"
   ],
   "redirect_url":"https://example.com/redirect",
   "additional_redirect_urls":[
      "https://example.org/redirect",
      "https://example.net/redirect"
   ],
   "access_grant_expires_in":30,
   "access_token_expires_in":3600,
   "refresh_token_enabled":true,
   "simultaneous_sessions_allowed":true,
   "default_scopes":[
      "address",
      "email"
   ],
   "additional_scopes":[
      "phone"
   ],
   "identity_provider_id":"123-123",
   "additional_identity_provider_ids":["123-124", "123-125"],
   "logo_uri":"",
   "additional_authenticator_type":"SMS_CHALLENGE",
   "template_set":"template1",
   "consent_disabled":true
}

Update Web Client

Some fields can be updated after creating a Web Client

  • Endpoint: /api/v1/configuration/web-clients/{client_id}
  • Method: PATCH

Path parameters:

Param Required Description
client_id yes Unique identifier of the Web Client.

JSON body parameters:

Only the fields that are sent in the request will be changed.

Param Required Example Description
name no "My web portal" Client name
grant_types no ["CLIENT_CREDENTIALS"] Set of Grant Types. Allowed values: AUTHORIZATION_CODE, CLIENT_CREDENTIALS, IMPLICIT, RESOURCE_OWNER_CREDENTIALS.
client_secret no "AF33E2BF29C54A4639AB…" Client Secret (not returned on GET)
redirect_url no "https://example.com/redirect" An URL to which the browser is redirected after successfully obtaining an Access grant. Used with Grant types AUTHORIZATION_CODE and IMPLICIT.
additional_​redirect_​urls no ["https://example.org/redirect"] Additional URLs that the user can be redirected to after successfully obtaining an Access grant.
access_​grant_​expires_​in no 30 The number of seconds that an Access grant is valid. Used with Grant type AUTHORIZATION_CODE.
access_​token_​expires_​in no 3600 The number of seconds that an Access token is valid. Used with Grant types AUTHORIZATION_CODE, CLIENT_CREDENTIALS and IMPLICIT.
refresh_​token_​enabled no true Issue refresh tokens
simultaneous_​sessions_​allowed no true Allow users to establish multiple sessions at the same time
max_​simultaneous_​sessions no 25 Limits the number of sessions when simultaneous sessions are allowed. Value must be between 2 and 25 (inclusive). Defaults to 25 when omitted and simultaneous_sessions_allowed is true.
default_scopes no ["profile"] Default scopes are the Scopes that are automatically assigned if a Client does not request any Scopes. If you want an Authorization request to fail when no Scopes are requested, leave this empty.
additional_scopes no ["address", "email"] Additional Scopes that can be requested by a Client during an Authorization request. The Default scopes can also be requested by a Client during the Authorization request.
identity_​provider_​id no "123-123" The Identifier of an existing Identity Provider you wish to be the primary/default for this client.
additional_​identity_​provider_​ids no ["123-124", "123-125"] Identifiers of additional existing Identity Providers that are able to be specified in the request.
logo_uri no "https://example.com/logo.png" The URL that refers to the logo of the client.
additional_​authenticator_​type no "SMS_CHALLENGE" You can specify Additional Authenticator types to give the user a choice when registering. Allowed values: "SMS_CHALLENGE".
template_set no "template1" Identifier of existing Template Set
consent_disabled no false When Consent is skipped, the user is not asked for Consent in the Authorization flow
open_id_connect no See table below JSON Object for OpenID Connect configuration. Required when openid is added to default_scopes or additional_scopes.

The following parameters are a part of the open_id_connect object.

Param Required Example Description
expiration_​time_​seconds depends 3600 The number of seconds that an ID Token is valid. It is used to calculate the exp expiration date claim in the ID Token. Required when openid is added to default_scopes or additional_scopes.
additional_​audiences no ["https://resource.example.com"] An array of case sensitive strings that identifies who is the audience of the issued ID Token. It is used to populate aud claim in the ID Token in combination with the client_id which is always included.
post_​logout_​redirect_​url no "https://redirect.example.com" This is Primary/Default Post Logout URL. The user will be redirected to this URL if no other URL is specified in the end session request.
additional_​post_​logout_​redirect_​urls no ["https://redirect.example.com", "https://postlogout.example.com"] An array of additional Post Logout Redirect URLs. This array contains the potential URLs that could be specified to be redirected to as part of the end session request.
front_​channel_​logout_​url no "https://front-channel-logout.example.com" A URL reachable on the Relying Party that will invalidate the session. This will be triggered after a successful logout via the end session page.

Example request:

PATCH /api/v1/configuration/web-clients/F167433E63CE8BD874D7 HTTP/1.1
Host: onegini.example.com
Content-Type: application/json

{
  "scopes": ["address", "email", "phone"]
}

Example success response:

HTTP/1.1 204 NO CONTENT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

The success response body is empty.

In the event of an error, one of the generic error codes will be returned.

Delete Web Client

This removes a Web Client.

  • Endpoint: /api/v1/configuration/web-clients/{client_id}
  • Method: DELETE

Path parameters:

Param Required Description
client_id yes Unique identifier of the Web Client.

Example request:

DELETE /api/v1/configuration/web-clients/365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B HTTP/1.1
Host: onegini.example.com

Example success response:

HTTP/1.1 204 NO CONTENT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

Error codes

One of the following responses will be returned, containing a JSON object with an error code, a message and details about the error.

HTTP status Error code Message
400 invalid_request One or more parameters is missing or incorrect. The details contain the missing or incorrect parameters.
401 unauthorized Provide valid credentials to get access to the API.
403 forbidden Operation is not allowed for the current user.
404 not_found Web Client configuration cannot be found for this client_id
409 conflict The Client ID already exists

Limitations

Some fields are references to other parts in the configuration of the Token Server. This API can only refer to existing identifiers for the following:

  • Identity Providers (both primary and additional)
  • Scopes (both default and additional)
  • Template Set

When an unknown identifier is passed, this API returns an HTTP status code 400 with error code invalid_request.