Tutorial (App Developer)
API Platform Version: 8.1 and later
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 page displays.
- On the Add App 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 for 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's Details page.
For more information, see How do I add an app?
Step 2: Provision App with Authentication Key
Next, you must provision the app with an authentication key. The Security section of the app's 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 when you add an app. 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 implementation (Sandbox or Live 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.
- Use the Search tool to find the API you're interested in. For details, see How do I search for information in the developer portal?
- Click the name in the search results. From the Overview page for the API, click Access in the upper right hand corner. The API Access Wizard launches at the first step, Select App.
- 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. The Endpoint page displays and presents a list of endpoints available for the current API (Sandbox or Live implementation).
- If the API supports both Sandbox and Live implementations, 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.
- 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 Live implementation 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 Forum 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 Connected section of the app's Details 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 app's Details page.
For more information, see How do I see the status of my app's connections to APIs? and How do I switch to a Live implementation?
- If you request access to the Live implementation, an API Access Request contract is not created for the Sandbox implementation.
- After the API Access Request for the Live implementation 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 implementations. This means that new contracts must be generated using the API Access function each time you switch.
- App Developers and API Administrators can edit the license scope (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 Live Access
If you performed and completed your testing on the Sandbox implementation, and need to upgrade your access to use the Live implementation, submit another API Access Request and select the Live implementation. See Step 3: Request API Access for instructions.
Step 7: Update Application with Live Endpoint
After you've been approved for access to the Live implementation and your status app status is "Activated," you must then update your app with the Live implementation URL. Refer to the App Security documentation in the API > Documentation section of your API for more information.
Step 8: Go Live
After you add the Live implementation URL to your application, your app is ready to go live.