Tutorial (App Developer)

How do I create a new app and configure it to consume APIs?

Step 1: Add New App

The first step in the process is to add an app.

To add an app:

From the Plus Menu, select Add a New App. The Add App Info page displays.
On the Add App Info page, specify the App Name, Version ID, Tags, Visibility (Public/Private), App Description, Version Description, and App Icon. All information here displays on your customer-facing App description.
- You can optionally upload an icon to uniquely identify your app. See How do I upload and crop icons? for more information.
- Your App description should include marketing, functional, and use case information.
Click Save. The app information is saved and posted to the App Details page. You can click Edit to update the App Name and Description.
To exit this operation, click Cancel.
For more information, see How do I create a new app?

Step 2: Provision App with Authentication Key

Next, you must provision the app with an authentication key. The Security section of the App Details page includes Shared Secret and Public Key Integration options for generating the credentials required to authenticate your app. A shared secret is automatically generated as part of the Add a New App creation process. If you prefer to use PKI keys, you can generate a Certificate Signing Request and upload it.

See App Security to determine which option best suits your requirements, configure the credentials, and continue to Step 3: Request API Access. For information on how to configure app credentials in the platform, click here.

Step 3: Request API Access

This process allows you to select the App you would like to connect to an API, and the environment (Sandbox or Production based on what the API supports). In addition:

If the App you would like to select shows a status of Contracted this means you already have access to the API. You can view the current status of the App on the App > API : Connections page.
Licenses - If the API supports Licenses with Scopes the Licenses page will display. If a Licenses page does not display, the App is assigned an Unrestricted License option (the default) which includes all of the API Version's operations in the scope as part of the API Access Request.
Legal Agreements—If the API requires any agreements to be accepted for setting up the connection, the Legal Agreements page displays.
When the Save button displays, this indicates that it is the last page in the wizard.
After clicking Save you will be redirected to the App > APIs : Connections page where you can view the status of the API Access Request.

Perform an API Search to target the API you would like to gain access to. See How do I search for information? for details.
After you find an API, click API name in the search results listing. The API Details screen displays.
Click Access in the upper right hand corner of the screen. The Select App screen displays.
In the Add column, click the radio button of the App Version you would to like API Access for and perform the following steps:
- Select the app version from the Version drop-down.
- Click the Add radio button of the app you are requesting access for the current API.
- To sort the app information in ascending or descending order, click the Application Name and Date columns.
Click Next to continue. The Endpoint page displays and presents a list of endpoints available for the current API (i.e., Sandbox or Production).
- If the API supports both Production and Sandbox environments, click the radio button of the API environment you are connecting the app too.
If available, click Next to continue to Licenses and/or Legal Agreements and then go to Step 8.

If the Licenses page displays, select a license option. The following options are supported.

Scope Level	Description
Unrestricted Access	This option includes all of the API Version's operations in the scope as part of the API Access Request.
Select Scope Later	This option allows the App developer to select the license scope at a different time. This option might be used if the App developer does not have visibility to see the licenses needed or if the App developer does not know the licenses to be selected.
Restricted Access	This option lets the user select the set of licenses to be added as the scope of the API Access Request.

Scope Level

Description

Unrestricted Access

This option includes all of the API Version's operations in the scope as part of the API Access Request.

Select Scope Later

This option allows the App developer to select the license scope at a different time.

This option might be used if the App developer does not have visibility to see the licenses needed or if the App developer does not know the licenses to be selected.

Restricted Access

This option lets the user select the set of licenses to be added as the scope of the API Access Request.

If the Legal Agreements page displays review and accept the agreements.
- If acceptance of multiple legal agreements is required, click on the tab to view each legal agreement.
- Note that all legal agreements must be accepted in order to proceed. If no additional legal agreements require acceptance, click Submit.
When the Save button displays, submit your API Access Request. You will be redirected to the App > APIs : Connections page. Your API Access Request status will be one of the following:
- Approved—This means that the API Access Request has been approved but is still pending activation by the API Provider.
- Activated—This means that the API Access Request was automatically approved and your app is connected to the API. Requests for access to the Sandbox environment are typically auto-approved.
- Access Pending—This means that the API Access Request is pending approval by the API Provider. Requests for access to a Production environment can sometimes be auto-approved, but a request may require additional review.
The API Access Request is processed and an "API Access Request" ticket is posted to the App Board for the related app with a "Pending" status. The ticket is identified with a contract request icon. The API is also visible in the APIs Used section of the My Apps page.
The Access Request is also posted to the APIs > Apps : Connections and App > APIs : Connection pages with an Pending Request status. Upon approval by the API Provider, the API Access Request status will change to Activated. Access to the API is granted and the API is visible in the APIs Used section of the My Apps > Details page.

For more information, see How do I see the status of my app's connections to APIs? and How do I go live in a production environment?

Notes:

If you request access for the production environment, an API Access Request contract is not created for the sandbox environment.
After the API Access Request for the production environment is approved, to gain access to the sandbox environment, you must run the API Access function again to generate a new contract for the sandbox environment.
Note that contracts are cancelled when you switch environments. This means that new contracts must be generated using the API Access function each time you would like to switch sandbox/production environments.
App Developers and API Administrators can edit the license scope (i.e., license option you selected on the 3. Licenses page) any time before the API Access Request is approved by the API Administrator.

Step 4: Build App and Configure App ID

The next step is to build your application and integrate the Sandbox Endpoint, App ID, and Shared Secret/PKI Key. This enables the ability to send requests from your application using the App ID assigned during the app creation process.

To enable your app to send requests:

You must configure the Authorization header of your application with the App ID.
You can obtain the App ID in the Security Credentials section of My Apps > App Details > Security.

The App Security topic provides information on how to configure the App ID. You can access the topic here: App Security

Step 5: Complete App Testing in App Sandbox

The next step is to set up accounts and data in your sandbox testing environment and test your app.

Step 6: Request Production Access

If you performed and completed your testing on the sandbox endpoint, and need to upgrade your access to use the production endpoint, submit another API Access Request and select the Production environment. See Step 3: Request API Access for instructions.

Step 7: Update Application with Production Endpoint

After you've been approved for production access and your status app status is "Activated," you must then update your app with the production endpoint URL. Refer to the App Security documentation in the API > Documents section of your API for more information.

Step 8: Go Live

After you add the production endpoint URL to your application, your app is ready to go live in the production environment.