Create an API client

Introduction

In this guide you will learn how to create an API Client definition in the IBM Security Verify Admin UI.

A privileged API client is required when an application needs to access APIs protected by OAuth without the delegated authority of an end user. A privileged API client uses the OAuth client credentials grant flow to obtain an Access Token.

IBM Security Verify's own APIs are protected with OAuth and so creating an API Client is the way that an application is granted authority to call privileged IBM Security Verify functions. The specific permissions granted to an API client are set as part of the client definition.

Pre-requisites

There are no pre-requisites for creating a stand-alone API Client. If you want to create an API Client that is associated with a custom application then that application definition must already exist.

Choose where to create the API client definition

A privileged API client can be defined as a stand-alone client or it can be defined within a custom application definition.

If the API client is required for an application that has no need for an application definition (because it only requires privileged API access), then it should be set up as a stand-alone client.

If the API client is required for a custom application which also needs an application definition (to support single sign-on or other OAuth flows), it makes sense to define the API client within that application definition).

Option 1 - Stand-alone API client

In the Admin UI, navigate to the Security > API Access page and select the Add API client button.

Option 2 - Application API client

In the Admin UI, navigate to the Applications > Applications page and edit the custom application that needs the privileged API client. In the application definition, select the API access tab and select Add API client button.

Define the API client

Entitlements

This is where you grant the permissions needed by the application using this API client.

Common permissions for a custom authentication application include:

• Authenticate any user
• Read users and groups
• Read second-factor authentication enrollment for all users

Common permissions for a custom registration application include:

• Authenticate any user
• Manage users and standard groups
• Manage second-factor authentication enrollment for all users

📘

Read vs Manage permissions

Many permissions have read and manage variants. In most cases, clients that are granted the manage permission are also able to perform read actions without being specifically granted that permission.

Custom Scopes

By default, an API client can request any scope. If you want to restrict the scopes that the client can request, select the Allow configured scopes only checkbox and add the scopes you want to allow.

Scopes are only relevant to a privileged API client if it will be used to call custom APIs. Scopes are not used for granting authority to IBM Security Verify APIs.

IP Filter

By default, an API client can request an access token from any IP address. If you want to limit the IP addresses that are valid for this API client, select the Enable IP filtering checkbox and enter the required IP address filter.

Additional properties

You can assign custom attributes to an API client. These can be used to store properties related to the API client. These values are not used by IBM Security Verify but can be accessed via API to lookup information about the API client.

Name and Description

The name and description of the API client are human-readable and used for administration and reporting only.

Obtain client credentials

The client credentials (client id and client secret) are generated when the API client definition is saved for the first time.

After saving the client definition, select the three dots on the client tile and select Connection details from the action menu. The client id and client secret values are shown on the connection details page. You can use the copy button by each item to add it to your paste-buffer.