Create API clients for web server applications

Important: As of December 1, 2020, 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 will be required to explicitly request the scopes they need. Existing API clients will continue to work after the update takes effect.

Marketplace Managers can create API clients for web server applications. These are traditional web applications that run on a server, for example ASP .NET, Java, Ruby on Rails or Node.js.

To create an API client for a web server application

Note: If the AppDirect logo appears in the upper-left corner of the page, when Manage > Marketplace appears in this topic, click the grid icon > Switch to | Store, instead.

  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 Web server application from the drop-down list.

  5. Select one of the following grant types:

    • Authorization Code—Used with server-side applications. The API client interacts with the user's web browser and receives API authorization codes. The Authorization Code grant type is the most common way for API clients to acquire access tokens that can be used to act on behalf of a marketplace user. When used by web server applications, the client secret is required when requesting the access token pin.

    • In the Authorization Code flow, API clients authenticate an end user and obtain an authorization code (a one-time use token). The code is then exchanged for an access token, and optionally a refresh token.

    • Password—Used with trusted applications. After a user gives their credentials to the application, the application requests an access token from the authorization server. After user credentials are verified, the authorization server returns an access token to the application.
    • Refresh Token—A special type of token that can be used to obtain a renewed access token at any time.
  6. Enter the redirect URL in the Redirect URL(s) field. Click Add URL to add additional redirect URLs.

  7. Under Allowed Scopes (Permissions), define the API client's permissions—that is, what it can do on behalf of a user and what resources it can access. Manage any of the following scopes as required:

    • OpenID Connect scopes—Allows an API client to verify the identity of an end user using the OpenID Connect protocol. Select one of the following:

      • ID Token—Allows this client to be used for OpenID Connect SSO.
      • Basic User Information—Allows an API client to access a user’s email address and basic profile information such as first name, last name, and email address contained in the UserInfo API.
    • User-level scopes—Select one or more of the user roles in the checklist to allow the API client to act on behalf of marketplace users with those user roles.

    See Scopes to learn more.

  8. (Optional) If you selected ID Token under OpenID Connect scopes in the previous step, the Persistent SSO field appears. Selecting this option gives marketplace users the option to remain logged in when authenticating with a trusted mobile application that has enabled persistent Single Sign-On (SSO), such as Mobile MyApps.

  9. If you selected the Authorization Code or Password grant type, or both, 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.

  10. (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.

  11. (Optional) If you selected Refresh Token under Grant Types, you can modify the default 30 days that the refresh token is active before it expires.
  12. 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.

  13. 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.