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 have the API Admin
scope.
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":"http://redirect.to",
"additional_redirect_urls":[
"http://redirect2.to",
"https://redirect3.to"
],
"access_grant_expires_in":300,
"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",
"public_base_uri":"",
"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, VALIDATE_ACCESS_TOKEN, RESOURCE_OWNER_CREDENTIALS |
redirect_url | yes | "http://redir.to" | 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 | ["http://redir2.to"] | Additional URLs that the user can be redirected to after successfully obtaining an Access grant. |
access_grant_expires_in | yes | 300 | The number of seconds that an Access grant is valid. Required for the User registration flow. |
access_token_expires_in | yes | 3600 | 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). |
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 Identity Providers that are able to be specified in the request. |
logo_uri | no | "http://d.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". |
public_base_uri | no | "https://example.com/sth" | When this Client gives access to the Token introspection API, it has some URI where it can be reached. Configure the base URI in which all calls to this client should originate. |
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 |
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",
"IMPLICIT"
],
"redirect_url":"http://redirect.to",
"additional_redirect_urls":[
"http://redirect2.to",
"https://redirect3.to"
],
"access_grant_expires_in":300,
"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",
"public_base_uri":"",
"template_set":"template1",
"consent_disabled":true
}
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/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":"http://redirect.to",
"additional_redirect_urls":[
"http://redirect2.to",
"https://redirect3.to"
],
"access_grant_expires_in":300,
"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",
"public_base_uri":"",
"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, VALIDATE_ACCESS_TOKEN, RESOURCE_OWNER_CREDENTIALS |
client_secret | no | "AF33E2BF29C54A4639AB…" | Client Secret (not returned on GET) |
redirect_url | no | "http://redir.to" | 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 | ["http://redir2.to"] | Additional URLs that the user can be redirected to after successfully obtaining an Access grant. |
access_grant_expires_in | no | 300 | The number of seconds that an Access grant is valid. Required for the User registration flow. |
access_token_expires_in | no | 3600 | 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). |
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 Identity Providers that are able to be specified in the request. |
logo_uri | no | "http://d.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". |
public_base_uri | no | "https://example.com/sth" | When this Client gives access to the Token introspection API, it has some URI where it can be reached. Configure the base URI in which all calls to this client should originate. |
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 |
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.