Tutorial (App Developer): Create a New App and Configure It to Consume APIs

Follow an example scenario for app setup.

Table of Contents

Step 1: Add New App

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

To add an app

  1. Go to Apps > Add App.
  2. 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.
  3. 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).

Note: for more information about requesting API access, see The API Access Wizard.

  1. Use the Search tool to find the API you're interested in. For details, see How do I search for information in the Community Manager developer portal?
  2. 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.
  3. Specify the app/app version that you want API access for.
  4. 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.
  5. If available, click Next to continue to Licenses and/or Legal Agreements and then go to Step 8.
  6. If the Licenses page displays, select a license option. The options shown below are supported.
    Scope LevelDescription
    Unrestricted AccessThis 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 AccessThis option lets the user select the set of licenses to be added as the scope of the API Access Request.
  7. 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.
  8. When the Save button displays, submit your API Access Request. You will be redirected to the Apps > My Apps > choose app > APIs 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.
  9. 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.
  10. The Access Request is also posted to the APIs > My APIs > choose API > select API > Apps page and Apps > My Apps > choose app > APIs page with a Pending Request status. Upon approval of the request, the status changes 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?

Notes:

  • 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 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 Apps > My Apps > choose app > Security.

For information on how to configure the App ID, see 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.