Administration Guide

API Settings

On this page

The API is one of the three instance families you configure in the Admin Center's Apps and Portals menu group, alongside the Web App and the Self Service Portal. The tabs of an API instance are General, Timezone, Authentication, and Application Gateway; the Authentication tab is hidden for an instance that uses Windows authentication. The accounts an API client signs in with are described in API Applications; how a client signs in to the API is described in Authentication.

Before you begin

  • Each instance family is gated on its own configuration permission; see Permissions Reference.
  • The list of single sign-on providers on the Authentication tab is returned only to administrators with Active Directory integration or security management rights.

In the Admin Center

Open the API instance

In the Apps and Portals menu group, select API. The menu lists the configured API instances; if only one instance exists, the menu collapses to that instance's tabs.

If no API instance is configured, the page shows a title, a description, and a sentence that links to the installation guide, in place of the instance's tabs.

Set the name and URL (General tab)

  1. Open the API instance's General tab.
  2. Under Name, enter a name for the instance. This name is for your reference only and is not visible to users.
  3. Under URL, review the auto-generated URL, and enter the correct address manually if needed. This URL is the API's base URL, the address that API clients call. The button beside the field opens the URL in a new tab; it is disabled while the field is empty.
  4. Save the tab. The Admin Center checks whether an API responds at the typed address. If it does, the settings are saved. If it does not, a dialog titled "API not found" asks whether to save the URL anyway: Save anyway saves it, Cancel does not.

When the instance URL and the system macro differ, the tab shows the alert "System macro differs from URL" and a read-only System macro field, which is used to generate direct links in workflow notifications. Two buttons set both fields to the same value: Update system macro with instance URL and Update instance URL with system macro.

NOTE: If the instance has been inactive for over 7 days, the General tab shows a warning that the instance appears to no longer exist, beside a Delete button. Confirming Delete instance? deletes the instance's settings.

Set the time zone (Timezone tab)

  1. Open the API instance's Timezone tab.
  2. In Timezone, choose the time zone for timestamp values. The list comes from the computer that hosts the Admin Center.
  3. Save the tab. Changes take effect in a few minutes.

The API converts the date and time values of record fields, view columns, query filter values and action-form fields that it sends and receives against this zone, so an API client sees one consistent zone. The API agrees with the database only when the selected zone is the one the stored values were written in. If the computer the API runs on does not know the selected zone, the API converts nothing: the values it sends carry the offset +00:00, and the values it receives are stored as UTC.

If no zone is set, the tab shows the time zone of the computer that hosts the Admin Center, while the API uses the time zone of the computer it runs on.

Configure authentication (Authentication tab)

The Authentication tab is not shown for an instance that uses Windows authentication. The tab shows nothing until its list of single sign-on providers has loaded.

  1. Open the API instance's Authentication tab.
  2. Under Password Authentication, select or clear Allow password authentication to choose whether users can sign in by entering their password. Password authentication must also be enabled in their user accounts: an account whose own Allow password authentication check box is cleared keeps no stored password, so no password matches it, whatever this setting is.
  3. Under SSO Authentication, select each single sign-on service to enable for this instance under Available Single Sign-On services:. The services are sorted by name. If none is configured, the tab shows "No services configured." with Add SSO providers.
  4. Click Save and Restart. The button appears, under a warning about the restart, once you change the form. It is disabled unless Allow password authentication or at least one service is selected. After a successful save, the API instance restarts.

When Allow password authentication is cleared, the API's /token endpoint refuses the password grant with the message "Password authentication is not allowed. Use the authorized authentication method instead." Single sign-on methods are described in Authentication Methods.

Save and Restart also saves the instance's other settings as they were loaded: its name, URL, time zone, host header, and system macro. Two values can change without your editing them:

  • A stored single sign-on service that no longer matches any listed service is removed.
  • If no time zone is set, the time zone of the computer that hosts the Admin Center is stored.

Set the host header (Application Gateway tab)

For an API deployed behind a proxy or load balancer:

  1. Open Application Gateway.
  2. In Host Header, enter the name of the HTTP header. This is a header name, not a host name.
  3. Save the tab. Changes take effect in a few minutes.