Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

General system properties

API clients API

search

API clients API

The API clients API allows the creation of new API clients via a REST API. It can be used in scripts to add many clients at the same time, or to edit or delete clients.

Authentication

All endpoints are protected with API client credentials (either Client Secret Basic or PrivateKeyJWT depending on the client authentication method). It requires an API client with the onegini_api_admin (Admin API) scope.

Initial API client

To use this API, there must be an API client configured that grants access to it. You can create this API client on the admin console.

Endpoints

List of API clients

This returns a list of all API clients. The client_secret is never returned in the response.

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

Request parameters:

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

Example request:

GET /api/v1/configuration/api-clients?page=1 HTTP/1.1
Host: onewelcome.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":"API client 1",
         "client_id":"365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B",
         "scopes":[
          "onegini_api_end_user",
          "onegini_api_user_registration"
         ],
         "public_base_uri":""
      }, 
      {
        … more api clients …
      }
   ]
}

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

Create API client

This creates a new API client.

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

JSON body parameters:

Param Required Example Description
name yes "API client 1" Client name
client_id yes "F167433E63CE8BD874D7…" Unique identifier for a client
authentication_method no "private_key_jwt" Identifies the authentication method for that client. Options are client_secret_basic and private_key_jwt. If not provided, it defaults to client_secret_basic.
client_secret depends "AF33E2BF29C54A4639AB…" Client secret (not returned on GET)
public_jwk depends EC or RSA public key Plain public key for private key JWT authentication in the Elliptic Curve (min P-256) or RSA (min 2048, max 4096 key length) x509 format. The OneWelcome Identity Platform favors jwks_uri, if provided, over statically defined JWK.
jwks_uri depends "https://authorization-server/jwks" URI of of the JWKS endpoint with public keys for private key JWT authentication.
scopes yes ["onegini_api_end_user", "onegini_api_user_registration"] Valid values are described in the API scopes
public_base_uri no "https://example.com/sth" When this client gives access to the Token introspection API, it has a URI where it can be reached. Configure the base URI from where all calls to this client originate.

Example request:

POST /api/v1/configuration/api-clients HTTP/1.1
Host: onewelcome.example.com
Content-Type: application/json
{
   "name":"API client 1",
   "client_id":"365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B",
   "client_secret":"919724DAE12CAB220407C34EDAE8438CEAE965CD0F8AD033A743C1F4BB4B15C4",
   "scopes":[
      "onegini_api_end_user",
      "onegini_api_user_registration"
   ],
   "public_base_uri":""
}

Example success response:

HTTP/1.1 201 CREATED
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Location: /api/v1/configuration/api-clients/365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B

The success response body is empty. The Location header contains the URL for this new API client.

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

Read API client

This returns an API client. The client_secret is never returned in the response.

  • Endpoint: /api/v1/configuration/api_clients/{client_id}
  • Method: GET

Path parameters:

Parameter Required Description
client_id yes Unique identifier of the API client

Example request:

GET /api/v1/configuration/api-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":"API client 1",
   "client_id":"365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B",
   "scopes":[
      "onegini_api_end_user",
      "onegini_api_user_registration"
   ],
   "public_base_uri":""
},

Update API client

Some fields can be updated after creating an API client.

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

Path parameters:

Parameter Required Description
client_id yes Unique identifier of the API client

JSON body parameters:

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

Parameter Required Example Description
name no "API client 1" Custom client name
authentication_method no "private_key_jwt" Identifies the authentication method for the client. The options are client_secret_basic and private_key_jwt. If not provided, it defaults to client_secret_basic.
client_secret depends "AF33E2BF29C54A4639AB…" Client secret (not returned on GET)
scopes no ["onegini_api_end_user", "onegini_api_user_registration"] Valid values are described in the API scopes
public_base_uri no "https://example.com/sth" When this client gives access to the Token introspection API, it has a URI where it can be reached. Configure the base URI from where all calls to this client originate.
public_jwk depends EC or RSA public key Plain public key for private key JWT authentication in the Elliptic Curve (min P-256) or RSA (min 2048, max 4096 key length) x509 format. The OneWelcome Identity Platform favours jwks_uri, if provided, over statically defined JWK.
jwks_uri depends "https://authorization-server/jwks The URI of the JWKS endpoint with public keys for private key JWT authentication

Example request:

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

{
  "scopes": ["onegini_api_end_user", "onegini_api_mobile_authentication"]
}

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

Delete API client

This removes an API client.

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

Path parameters:

Parameter Required Description
client_id yes Unique identifier of the API client.

Example request:

DELETE /api/v1/configuration/api-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 are 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 "API Client" configuration cannot be found for this client_id
409 conflict The client ID already exists for a different API client, Web client, or Device.

On this page