Register applications

External applications can use the REST web service APIs to integrate with Oracle Commerce. You must register an application to enable it to access Commerce data and functionality.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Registering an application automatically generates the following:

• An application ID that identifies the application internally.
• An application key that you use to authenticate the application.

The application key is a JSON Web Token (JWT) from the Oracle Commerce OAuth server. The registered application exchanges the key for an access token as part of the authentication flow. For more information, see Use the application key for authentication.

You can register an application in the administration interface or by using the Admin API. Both methods are described below. Note that only the API enables you to specify when the application key expires. If you register an application in the administration interface, or register it using the API without specifying an expiration date, the application key does not expire until you revoke it explicitly.

Register an application in the administration interface

To register an application in the administration interface:

1. Click the Settings icon.
2. Click Web APIs and display the Registered Applications tab.
3. Click the Register Application button.
4. Enter a name for the application.
5. Click Save.

   The application ID and application key are automatically generated and the application is added to the list on the Registered Applications page.

To acquire the application key:

1. Click the Settings icon.
2. Click Web APIs and display the Registered Applications tab.
3. Click the name of the application whose key you want to get.
4. Click the Application Key box to reveal the key.
5. Copy the key and provide it to the application developer.

   See Use the application key for authentication for more information.

To reset the key for a registered application:

1. Click the Settings icon.
2. Click Web APIs and display the Registered Applications tab.
3. Click the name of the application whose key you want to reset.
4. Click Reset.

   The new application key is automatically generated. The existing application key is automatically revoked and can no longer be used to authenticate the application.

To unregister an application:

1. Click the Settings icon.
2. Click Web APIs and display the Registered Applications tab.
3. Click the name of the application you want to unregister.
4. Click Delete.
5. Click Save.

   The application’s ID is removed from the system and its application key is automatically revoked.

Register an application using the Admin API

You use the createApplicationID endpoint to register an application using the Admin API. For example:

POST /ccadmin/v1/applicationIds  HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>
{
    "name": "sampleApp",
    "lifetimeDays": 90,
    "type": "application"
}

In this example, the lifetimeDays property is used to set the application key to expire after 90 days. The maximum value this property can be set to is 365; if you specify a larger value, the value will be set to 365. If you do not set a value for lifetimeDays, or set it to -1, the application key will not expire until you revoke it explicitly.

The response includes the values for the application to use for authentication. For example:

{
    . . .
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3ZjkzNjQ1Ni01ZmUyLTQ5NTQtODk0NS1kYTMyZTZmOTFjNzUiLCJpc3MiOiJhcHBsaWNhdGlvbkF1dGgiLCJleHAiOjE2ODYwNzkzMzEsImlhdCI6MTY1NDU0MzMzMX0=.imjcnTgBZE8+AADDB/h/RxBzDFX6EbQ/+1DJtsprM9E=",
    "expirationTime": 1662319331,
    "name": "sampleApp",
    "id": "7f936456-5fe2-4954-8945-da32e6f91c75",
    . . .
}

The value of id is the application ID, and the value of token is the application key. The expirationTime indicates when the application key expires, expressed as the number of seconds elapsed since the beginning of the Unix epoch (00:00:00 UTC, Thursday, 1 January 1970).