API Access

Set up API access contracts for your app and manage API access requests.

Table of Contents

How do I get API access for my app?

After you have defined your app on the platform and chosen one or more APIs that include functionality you want to use in your app, the next step is to connect your app to an API by requesting API access.

In some cases, when you create your app, connections to one or more APIs might be created automatically. If automatic connections are created, you can manage them in the same way as connections you create yourself (see below).

Note: Before you can make a call to an API you must add credentials for your app. See How do app credentials work? for details.

You can also view a tutorial video on YouTube: Add an App and Subscribe to an API (external link).

Here are some general points relating to API access:

  • If your app shows a status of Contracted, you already have access to the API. For example, you might already have a Sandbox contract but now want to request access to the Live implementation. To view a summary of the API contracts for your app, go to the Apps > My Apps > choose app > APIs page.
  • Licenses—If the API supports licenses, you are offered a list of available licenses as part of the API Access Wizard. If the API doesn't support licenses, this tab is not present.
  • Legal Agreements—If the API requires any agreements to be accepted for setting up the connection, the Legal Agreements page is displayed as part of the API Access Wizard.
  • After clicking Save you are redirected to the Apps > My Apps > choose app > APIs page, where you can view the status of the API access request.

The API Access Wizard

When you go to the Overview page of an API you want to connect to, and click the Access link in the top right corner, the API Access Wizard is launched.

Depending on the options that have been set up for the API you're connecting to, the API Access Wizard includes two or more of the following tabs:

  1. Select App (all): specify the app that you want the API connection for. If you have more than one version of your app, make sure you specify the correct version. Click Add, and then click Next. Note:
    • Versions prior to 2019.1.12: Apps available for contracting with the API are displayed in a list. Find the one you want, then click the Add button.
    • 2019.1.12 and later: In the App Name field, type any part of the app name to search for the app. When you type two characters, the first 10 matches are displayed (any part of the app name). Keep typing to find additional matches. Then, in the App Versions field, choose the version.
  2. Endpoint (all): Choose the implementation you want API access to, Sandbox or Live, and then click Next.
  3. Policies (if the API uses policies and the API does not use the Licenses feature): If any QoS policies are available for the API, you can choose one or more (not required). All QoS policies available for the tenant are displayed, unless this tab is disabled by a Site Admin setting (see Show policies on API Access wizard). Note that if the API uses licenses (next tab), the QoS policies that are associated with the license are the ones that apply to your API contract.
  4. Licenses (if defined for the API): Choose Unrestricted Access or, if licenses are available, click Restricted License and choose one of the license options. Click Next.
  5. Legal Agreements (if defined for the API): If the API includes one or more legal agreements (EULA, end-user license agreement), you'll need to accept the legal agreement in order to complete the API access contract. Review the agreement, click Accept, and then click OK at the confirmation prompt. If there is more than one EULA, each is displayed in a separate tab and you must accept each separately.

To request API access

  1. Use the Search feature to find an API you're interested in using. For details, see How do I search for information in the Community Manager developer portal? You can click through from the search results to the API Details page and browse the API documentation via the Documentation link on the left.
  2. 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 the API connection for. Click Next.
  4. At the Endpoint page, choose the implementation you want access to, Sandbox or Live, and then click Next.
  5. Conditional: if policies are defined for the API you will see a list, and can choose one or more policies for your API access contract. Click Next.
  6. If the Licenses page displays, select a license option. The options available to you depend on how the individual API is set up.
  7. If there are any legal agreements associated with the API, you'll need to accept each agreement as part of your API access request. If there are multiple agreements, each is in a separate tab. Review each agreement and click Accept, then confirm your acceptance.
  8. Click Save.

API Contract Status

Depending on how the API is set up, and the access you requested, the status of your API access request will be one of the following:

  • Approved—The API Access Request has been approved but is still pending activation by the API Provider.
  • Activated—The API Access Request was automatically approved and your app is connected to the API. Requests for access to the Sandbox environment are often, but not always, set up for auto-approval.
  • Access Pending—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 entry is posted to the Forum for the 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.

For pending requests, the access request is also posted to the applicable pages for both apps and APIs, with a status of Pending Request:

  • Apps > My Apps > choose app > APIs
  • APIs > My APIs > choose API > Apps

Upon approval by the API Provider, the API Access Request status changes to Activated. Access to the API is granted and the API is visible in the APIs Connected section of the app's Details page.

See How do I see the status of my app's connections to APIs? and How do I switch to a Live implementation?

Contract Generation and Approval:

After the API access request is completed, a contract post is created and the request is submitted to the Admin Team for approval. Some points to note:

  • You can view the request in the Apps > My Apps > choose app > Forum page.
  • If the request is automatically approved, the status is Activated.
  • If the request is not approved, the status is Pending Approval.
  • Pending requests are reviewed and approved by the API Admin team.

Notes:

  • If you request access to the Live implementation, an API Access Request contract is not created for the sandbox environment.
  • 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 environments. This means that new contracts must be generated using the API Access function each time you would like to switch Sandbox/Live implementations.
  • App Developers and API Administrators can edit the license scope (the license option you selected on the Licenses page) any time before the API Access Request is approved by the API Administrator.

What is an automatic API access connection?

In some cases, one or more APIs on the platform might be set up so that when you create your app, your app automatically has a connection with that API.

You can view all your API connections by going to Apps > My Apps > choose app > APIs. All contracts, active or pending, are displayed.

If automatic connections are created, you can manage them in exactly the same way as connections that you create yourself.

How do I request a second contract with the same API?

When you click the Access button to access a specific API, as explained in How do I get API access for my app? above, you can create a contract in either the Sandbox or Live implementation. However, once you have a contract, you can't create a second contract, in the other environment, the same way.

If you have an existing contract with the API, and want to create a contract in the other environment, there's another way to do it, via the APIs page. Follow the instructions below.

To request a second contract with the same API

  1. From the app's Details page, on the left menu bar, click APIs. All APIs that your app has contracts with are shown on this page, along with the status of each contract.
  2. Find the API on the list. You'll see the existing contract in the column for either the Sandbox or Live implementation.
  3. In the other column, click Request Access. Specify licenses, if applicable, and click Save.

What license options are supported for API access requests?

If you are requesting access to an API that offers different licenses, you'll be able to choose the license that most suits your needs as part of the API Access Wizard. The specific licenses offered for each API are determined by the API owner.

Once you've selected a license and completed the API access request, you can still modify your request while it's pending approval. Once it's approved, you can't modify your request; you'd have to cancel the contract and request a new one.

Note: If the API offers licenses, you will need to specify a license before you can get API access. The license defines the terms of your API access contract. Even if the API Access Wizard allows you to proceed without specifying a license at the time, your request is not approved until you've chosen a license. If this occurs, you'll be able to go back and modify your pending request later. For more information on modifying a pending request, see How do I edit the license in my API access request?

How do I determine what kind of license support an API offers?

When you make an API access request, the Licenses tab of the API Access Wizard includes a summary of all the licenses available. This generally includes a brief description of each license.

If you want more detailed information, check the documentation for the API. The documentation should include details on the different licenses available for the API and the terms of each license. If you can't locate the information you need, contact the API Administrator.

What happens if the license changes for an API I'm using?

If a license is updated, any pending or approved API access requests are automatically updated.

How do I cancel an API access request?

If you want to cancel an API access request, follow the instructions below.

To cancel an API access request

  1. Go to Apps > My Apps > choose app > APIs.
  2. Find the entry for your API access request and click Cancel.
  3. Enter information in the Comments box and click Confirm.

How do I edit the license in my API access request?

An app developer can change the license for a specific API access request prior to the request being approved by the API Administrator. There are a variety of different scenarios the can require changing the license. For example, if the API now offers a different license that better suits your needs, you can modify your request.

Note: You can update the license configuration at any time prior to the API Access Request being approved by the API Administrator. Once the API Access Request is approved, the Edit Scope function is disabled.

To edit the license

  1. Go to Apps > My Apps > choose app > APIs.
  2. Select an API access request that has a status of Access Pending.
  3. Click Edit Scope. The API Access Wizard launches and loads the Licenses page.
  4. Click the radio button of the license option you would like to change. If you select "Restricted Access," select the QoS policies you would like to assign to the License configuration.
  5. Click Save.

How do I disconnect my app from an API?

You can disconnect your app from an API it is consuming in either the Sandbox or Live implementation. Go to Apps > My Apps > choose app > APIs. Find the contract on the list, click the arrow to the right of the contract, and choose Cancel. At the prompt, enter a comment and click Confirm. For more information, see How do I update approved API access requests?