Create API clients for non-interactive applications

Important: As of December 1, 2020, two features that affect API clients are deprecated. The OAuth 1.0 protocol is no longer available as an API client type for non-interactive applications (you can only use OAuth 2.0). Existing OAuth 1.0 API clients will continue to work. For enhanced security, AppDirect recommends that you use OAuth 2.0, and that you migrate existing OAuth 1.0 API clients to OAuth 2.0. In addition, when you create a new API client or edit an existing API client, the Requested scopes policy option is no longer available. All new API clients are required to explicitly request the scopes they need. Existing API clients continue to work. If you update and save either of these settings, you cannot revert to the previous configuration.

Marketplace Managers can create API clients for non-interactive applications. These are server-to-server (machine-to-machine) applications, for example command-line tools, daemons, IoT devices, or services running on the back end.

To create an API client for a non-interactive application

  1. Go to Manage > Marketplace > Settings > Integration | API Clients. The API Clients page opens.
  2. Click Create API Client. The API Client Settings dialog opens.
  3. Enter a name for the API client.

  4. Under Client Type, select Non-interactive application from the drop-down list.

  5. (Optional) Under Protocol, select the OAuth protocol used by your API client. AppDirect recommends OAuth 2.0, which is enabled by default. You cannot select OAuth 1.0 after December 1, 2020.

  6. If you selected OAuth 2.0 in the previous step, a grant type sub-section appears, with client credentials preselected as the grant type (cannot be changed). This grant type gives applications a way to access their own service account, for example, to access other data stored in their service account via the API. An application requests an access token by sending its credentials, its client ID and client secret to the authorization server. After application credentials are verified, the authorization server returns an access token to the application. This grant type does not generate a refresh token.

  7. Under Allowed Scopes, select the system-level scope (permission) for this API client from the drop-down list. The scope you select defines if this OAuth 1.0 or OAuth 2.0 client should be granted read only or read and write access.

    See Scopes to learn more.

  8. If you selected OAuth 2.0 as the API client's protocol, the Requested Scopes Policy section opens, with a Require API Clients to Request Scopes setting. This setting is enabled by default for all new API clients. When this recommended setting is enabled, the marketplace no longer returns access tokens with all allowed scopes, when no scopes are requested by the API client.

    Note: To ensure compatibility with previously created API clients, this setting is disabled for all existing API clients. API developers of existing integrations are encouraged to update their integrations with the new setting enabled, thereby requiring the API client to request specific scopes they need. To disable this setting, clear the checkbox.

  9. (Optional) Allowed IP Addresses. Configure a comma-separated list of IP addresses from which this API client is allowed to send requests. Leave blank to allow all IP addresses. CIDR notation is supported.

  10. Click Save Settings. The new API client is created, along with a Consumer Secret and Consumer Key. A message appears that includes the Consumer Secret and a warning that you should copy and store the secret in a safe location because it cannot be retrieved after the message is dismissed.

  11. Copy the Consumer Secret, then paste it in a file where you can retrieve it later as needed.

    Note: If you cannot locate the Consumer Secret, you can regenerate it. See Edit API clients to learn more.