API Access

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

How do I get API access for my app?
What is an automatic API access contract?
What license options are supported for API access requests?
How do I determine what kind of license support an API offers?
What happens if the license changes for an API I'm using?
How do I cancel an API access request?
How do I edit the license in my API access request?
How do I disconnect my app from an API?

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

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 Production access. To view a summary of the API contracts for your app, go to the My Apps page and choose the app. From the App Board, click APIs on the left to view the App > API : Connections 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 App > APIs : Connections page where you can view the status of the API access request.

The API Access Wizard

When you go to the homepage 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 specific API you're connecting to, the API Access Wizard will include three or more of the following tabs:

Select App (all): If you have more than one app, choose which one you want the API connection for. If you have more than one version of your app, make sure you choose the correct version. Click Add, and then click Next.
Endpoint (all): Choose the environment you want API access for: Sandbox or Production, and then click Next.
Policies (if defined and the API does not use the Licenses feature): If one or more QoS policies are available for the API, you can choose one or more (not required). 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.
Licenses (if defined for the API): If the API offers licensing options you have some choices here. Choose Unrestricted Access or, if licenses are available, click Restricted License and choose one of the license options. Click Next.
Legal Agreements: This tab is always present, even if there are no agreements to accept. If the API includes one or more legal agreements (EULA, end-user license agreement), you will 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:

Use the Search feature to find an API you're interested in using. See How do I search for information? for details. You can click through from the search results to the API details page and browse the API documentation via the Documents link on the left.
From the API Details page, click Access in the upper right hand corner of the screen. 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 like API access for. If you have multiple versions, make sure the right version is selected and then click Next.
At the Endpoint page, choose the environment for which you're requesting access, and then click Next.
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.
If the Licenses page displays, select a license option. The options available to you depend on how the individual API is set up.
If there are any legal agreements associated with the API, you will 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.
Click Save. The API access request is sent, and you are redirected to the App > APIs : Connections page.

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

For pending requests, the Access Request is also posted to the APIs > Apps : Connections and App > APIs : Connections pages with a status of Pending Request. 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 Used section of the My Apps > Details page.

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

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 contract in the My Apps > Board.
The contract is labeled as an "API Access Request" and is identified with a contract icon.
If the request is automatically approved, the ticket status is Activated.
If the request is not approved, the ticket status is Pending Approval.
Pending requests are reviewed and approved by the API Admin team.

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 (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 your App Details page (My Apps > choose the app); on the left menu, click 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.

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:

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

If you would like to cancel an API access request after it's submitted, you can post a comment to the API Access Request Board item requesting that the API Administrator cancel the request. For more information, see How do I ask or answer questions relating to a post or ticket?

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:

Go to Apps > APIs.
Select an API access request that has a status of Access Pending.
Click Edit Scope. The API Access Wizard launches and loads the Licenses page.
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.
Click Save to commit your changes.

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 Production environment by using the Cancel or Suspend functions. Go to My Apps, choose the app, and then in the left pane click APIs. For more information, see How do I update approved API access requests?