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:
Example success response:
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:
Example success response:
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:
Example success response:
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:
Example success response:
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:
Example success response:
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. |
