Getting Started

Get familiar with key concepts and what need to be done before using Fonn API:

  • Concepts

  • Authorization

    • Obtaining API keys

    • Including API keys in request

  • User impersonation

Concepts

Fonn API is based on HTTP protocol and uses UTF-8 encoded JSON for representation of payloads in request and responses. There are couple of dedicated endpoints for specific operations like file uploads which rely on different content type. Details on all available endpoints can be found in API Reference. API supports user impersonation.

Authorization

API is secured, it controls whether requested data or operations are allowed, therefore every API call must be authorized by two secret API keys. These keys must be included as part of HTTP request headers:

  • Subscription Key: Ocp-Apim-Subscription-Key HTTP header

  • Access Token: Authorization HTTP header

Obtaining API keys

You need to have active subscription in Developer Portal and be an organization administrator in Fonn App to generate both API keys.
If you already have an account which is part of organization, please ask your organization administrator for the keys.
If you want to register new account and organization, please follow steps below.

Important: provide identical email address in all steps of the process.

1. Create Fonn Application User account

Navigate to https://app.fonn.io/register and complete registration process.

2. Create Developer Portal account

Navigate to Registration and complete registration process.

3. Request for API Subscription and Organization Administrator

  • Sign In on Developer Portal

  • Navigate to Profile

  • Add new subscription. It will require activation - see next bullet.

  • Please fill in the form below. All fields are mandatory. We will send you back confirmation when subscription is activated, organization is created with your account as administrator.

Subsequent steps can be performed when we confirm that subscription has been activated and organization setup is completed.

4. Obtain Subscription Key

  • Sign In on Developer Portal

  • Navigate to Profile

  • Subscription Keys are accessible for active subscriptions

    Note that two keys are for seamlessly changing access keys without service interruption.

    Suppose you leaked an access key and want to change it. If there would be just one key and you have regenerated it - then your application services will be unable to access the API until they are reconfigured to use the new key. That might result in downtime or degradation up to several dozen minutes long and even more depending on how your application services support reconfiguration.

5. Obtain Access Token

  • Login to Fonn as Organization Administrator

  • Navigate to organization settings by clicking on ORGANIZATION label at upper right corner if header

  • In left-side menu expand Integrations section and click API option

  • From drop down select user on-behalf of which API requests will be made by default (token identity) and click Generate token.

    • We recommend to use dedicated user accounts for API access tokens instead of accounts that are assigned to regular users.

    • You can have multiple tokens, but you can generate only single token for each user.

    • Leverage user impersonation capability to amend the effective token identity (act on-behalf of other user).

    • Effective token identity must have permissions (e.g. access to projects) for the operations that will be executed through API.

  • View access token anytime by clicking View Token next to the related user.


Workspace Access Token - access to multiple organizations

Regular Access Token allows to access data only in scope of organization it was generated in. Integration partners may have company structure that consists of multiple Fonn's organizations and wish access data from all of them without need to generate/manage multiple Access Tokens. Fonn addresses that requirement - we support interaction with multiple organizations by the Workspace Access Token.

  • Token can be retrieved only by sending direct support ticket.

  • Token is included in request the same way as regular Access Token

  • User impersonation is mandatory in requests made to project scoped endpoints when authorized by Workspace Access Token.

Moreover, with Workspace Access Token it is possible to create new organizations programmatically through API Create Organization endpoint.

Including API keys in request

Once both subscription key and access token are known, include them in HTTP request headers.

Ocp-Apim-Subscription-Key: <Subscription Key>
Authorization: <Access Token>

Sample cURL command with headers:

curl --location '<url>' --header 'Ocp-Apim-Subscription-Key: <subscription Key>' --header 'Authorization: <access token>'

User Impersonation

Note: This is optional feature, you can skip it if the token fixed user identity satisfies your API interaction needs.

Access Token has fixed identity of the user that has been selected when token was generated in the Fonn UI. In many scenarios the intention act as other user than token fixed identity. User impersonation is an mechanism allowing user - impersonator with sufficient privileges to act as another impersonated user and make actions on his/her behalf. Impersonation is possible on most of the API requests. Impersonation amends effective token identity in a way that it is no longer fixed but can be specified individually on each request.

Restrictions applicable to impersonation:

  • It works in the scope of an impersonator’s organization - impersonated user must be managed by the same organization or be a member of the same organization administrator.

  • Only Organization Admin is allowed to impersonate - user selected for access token generation must be in this role.

  • Only users created through API can be impersonated - impersonated user is identified by External Id that value can be specified only when account is created via API

  • Permissions of impersonated user are respected - i.e. if impersonated user cannot create change request, action will be denied even if impersonator could.

To impersonate request set impersonatedUserExternalIdheader value to the External Id of impersonated user.

curl --location '<url>' --header 'impersonatedUserExternalId: <External Id>' --header 'Ocp-Apim-Subscription-Key: <subscription Key>' --header 'Authorization: <access token>'

Rate limiting

The rate-limit policy prevents API usage spikes on a per subscription basis by limiting the call rate. When the call rate is exceeded, the caller receives a 429 Too Many Requests response status code. Client code should take it into consideration by implementing retry policy with waiting time and evenly distributing calls.