Create API clients for single page web 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 single page web server applications. These are JavaScript front-end applications that run in a browser, for example Angular, jQuery or React.

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 Single page web application from the drop-down list.
   Note that for single page web application API clients, the only available grant type is implicit. It is selected by default and cannot be changed. The implicit grant type is used with applications that run on the user's device. The user is asked to authorize the application, then the authorization server passes the access token back to the user-agent, which passes it to the application. The implicit grant type is similar to authorization code with notable differences:

   • It is intended for browser or mobile apps that cannot keep client secrets because all of the application code and storage is easily accessible (for example, single-page web apps).
   • The authorization server returns the access token directly, instead of a code that is exchanged for a token.
   • Refresh tokens are not supported.

5. Enter the redirect URL in the Redirect URL(s) box. Click Add URL to add additional redirect URLs.

6. 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 allows the API client to act on behalf of marketplace users with those user roles.
     For more information, see Scopes.

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

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

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. 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. For more information, see Edit API clients.