API Clients API

This allows the creation of new API 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 with API client credentials (either Client Secret Basic or PrivateKeyJWT depending on the client authentication method. It requires an API client with the scope onegini_api_admin (Admin API).

Initial API client

In order to use this API there must be an API client that gives access to this API. There are two ways to create such an API client.

  1. Create an API client via the Admin console.
  2. Configure the credentials for the API client in the deployment file of the Token Server engine. The Token Server will create an API client with these credentials and the scope onegini_api_admin.
Environment variable Required Description
BOOTSTRAP_​ADMIN_​API_​CLIENT_​CLIENT_​ID No Unique identifier for a client
BOOTSTRAP_​ADMIN_​API_​CLIENT_​CLIENT_​SECRET Only if a clientId is configured Client secret

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. Page number defaults to 0.

Example request:

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

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

Create API Client

This creates an API Client from scratch

  • 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" Indicates 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 P-256 public key Plain public key for private key JWT authentication. The Onegini Token Server will favour jwks_uri if provided over statically defined JWK.
jwks_uri depends "https://authorization-server/jwks" Uri of JWKS endpoint with public keys for private key JWT authentication.
scopes yes ["onegini_api_end_user", "onegini_api_two_way_otp"] 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 some URI where it can be reached. Configure the base URI in which all calls to this client should originate.

Example request:

POST /api/v1/configuration/api-clients HTTP/1.1
Host: onegini.example.com
Content-Type: application/json
{
   "name":"API client 1",
   "client_id":"365DADBA53849C3B67E7E3B736AA8C0701A98D6DC68047CD2AA10094DDFD835B",
   "client_secret":"919724DAE12CAB220407C34EDAE8438CEAE965CD0F8AD033A743C1F4BB4B15C4",
   "scopes":[
      "onegini_api_end_user",
      "onegini_api_two_way_otp"
   ],
   "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 will be 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:

Param 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_two_way_otp"
   ],
   "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:

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

JSON body parameters:

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

Param Required Example Description
name no "API client 1" Custom client name
authentication_​method no "private_key_jwt" Indicates authentication method fot 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)
scopes no ["onegini_api_end_user", "onegini_api_two_way_otp"] 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 some URI where it can be reached. Configure the base URI in which all calls to this client should originate.
public_jwk depends EC P-256 public key Plain public key for private key JWT authentication. The Onegini Token Server will favour jwks_uri if provided over statically defined JWK.
jwks_uri depends "https://authorization-server/jwks Uri of 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 will be returned.

Delete API Client

This removes an API Client.

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

Path parameters:

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