API Access

Set up API access contracts for your app.

Table of Contents

1. How do I get API access for my app?
2. What License options are supported for API Access Requests?
3. How do I edit the License Scope (API Administrator)?
4. How do determine what kind of license support and app access an API has?
5. What happens if the License and Scope configuration of an API I have access to changes?

How do I get API access for my app?

After you have chosen one or more APIs that include functionality you want to use in your app, the next step is to request API access. Note that you must have one or more apps defined before requesting API Access.

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

To request API access

1. Use the Search feature to locate an API you'e 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..
2. From the API Details page, click Access in the upper right hand corner of the screen. The Select App screen displays.
3. 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.
4. Click Next. 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.
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 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.

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 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.
9. 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.
10. 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.
11. See How do I manage API connections? 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.

• 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 will display as "Activated."
• If the request is not approved, the status will display as "Pending Approval."
• Pending requests are reviewed and approved by the 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 (i.e., license option you selected on the 3. Licenses page) any time before the API Access Request is approved by the API Administrator.

To connect your app to an API

1. Perform an API Search to target the API you would like to have access to. See How do I search for information? for details.
2. After you find an API, click the API name in the search results listing. The API Details screen displays.
3. On the API Details page, select the version of the API you would like to request access to from the Version menu, then click Access to launch the API Access Wizard. The 1. Select App page of the API Access Wizard displays
4. Select the app version from the Version drop-down, and 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.
5. After making your selection, click Next. The 2. Endpoint page displays.
6. In the Environment section. click the radio button (Production or Sandbox) of the API endpoint you would like to request access to.
7. After making your selection, click Next. The 3. Licenses page displays. Here you will select a license option. The options shown below 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.

   To select a license option, click the radio button of the option.
8. If the current API includes published legal agreements, the Next button displays. Click Next. The 4. Legal Agreements page displays. If the API does not include published legal agreements, click Save and skip to step #11.
9. Review the Legal Agreements for the API and click Accept or Decline.
10. The selected API may require acceptance to multiple legal 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.
11. 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.
12. The Access Request is also posted to the APIs > App and App > APIs pages with an Access Requested status. Upon approval by the API Admin, the API Access Request status will change to Active. Access to the API is granted and the API is visible in the APIs Used section of the My Apps page.

Back to top

What License options are supported for API Access Requests?

The API Access Wizard includes a Licenses tab that allows you to configure the level of restrictions you would like to assign before granting an App access to an API.

Three levels of scope are supported:

Note that the App Developer or API Administrator can update the license scope 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.

• The App Developer can update the API Access Request and select the license scope using the Edit Scope function on the Apps > APIs page. See How do I edit the license scope (API Administrator)?
• The API Administrator can update the API Access Request and select the license scope using the Edit Scope function on the APIs > Apps page. See How do I edit the license scope (App Developer)?

The following license scope levels 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.

Back to top

How do I edit the License scope (API Administrator)?

An API Administrator can change the license scope for a specific API Access Request prior to approving the request. There are a variety of different scenarios the can require changing the license scope. For example, if the desired license was not be available at the time the API Access Request was submitted, or if the license access level for the API changed (i.e., from Unrestricted Access to Restricted Access), etc.

Note: You can update the license scope 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 scope:

1. Go to APIs > Apps.
2. Select an API Access Request that was recently submitted and has a status of "Access Pending."
3. Click Edit Scope. The API Access Wizard launches and loads page 3. Licenses.
4. Click the radio button of the License option you would like to change.
5. Click Save to commit your changes.

Back to top

How do determine what kind of license support and app access an API has?

The API documentation should include details on the different kinds of licenses available for the API and what access apps will get for each license. If you cannot locate this information in the API documentation, contact the API Administrator.

Back to top

What happens if the License and Scope configuration of an API I have access to changes?

If a license is updated, or a scope that is referenced by a license, any pending or approved API Access Requests are automatically updated.

Back to top