Skip to content

Accessing the Formbird API

The Formbird API is accessible using either of the following methods:

  • Key / Token Authentication; or
  • Cookie Authentication

Tip: Consider creating a dedicated Formbird Account for any integration work. This will allow you to restrict the Account to the minimum required to perform its intended operation.

Key / Token Authentication

To begin using the Key / Token Authentication method you will need to request an API Key from your system administrator. You will need to specify the Formbird Account you wish to connect with along with the IP addresses that you are making the calls from. The system administrator will configure your Formbird Account with this additional information and supply you with the apiKey to use in your API calls.

Below is an example of the additional configuration values added to a Formbird Account Security Document to enable API access using an apiKey:

{
    "apiHosts" : ["127.0.0.1"],
    "apiKey" : "bf5b0500-9332-11e6-9c03-853f647fe4a4"   
}

Once configured, you will be able to authenticate by simply suppling the apiKey within the request. The recommended method of doing this is to supply the apiKey in the request Header (available from v2.1.27 onwards), as shown below:

curl http://localhost:3000/api/document/dcfc63d0-9442-11e7-a6b2-d9cc8e84f3a6 \
-H "apiKey: bf5b0500-9332-11e6-9c03-853f647fe4a4"

If the client you are using to perform the calls does not support this method or you are using a earlier version of the Formbird application (pre v2.1.27), you may supply it as a URL parameter, as shown below:

curl http://localhost:3000/api/document/dcfc63d0-9442-11e7-a6b2-d9cc8e84f3a6?apiKey=bf5b0500-9332-11e6-9c03-853f647fe4a4

Accessing the Formbird API using Cookie Authentication is a two step process. First step is to authenticate your Formbird Account with the server; once authenticated, submit your cookie on each subsequent API call.

To authenticate, make the following POST to the authentication service:

POST /auth/login/local

Arguments * email: users login name (ie. email address) * pass: users password

Example Request 

curl http://localhost:3000/auth/login/local \
 -d "email=your.name@yourcompany.com&pass=yourPassword" \
 -c ./cookie.txt

The above call produces a cookie (stored in cookie.txt) which can then be submitted on each subsequent API call using the cookie option -b in curl.

Choosing a method

The remaining examples in this guide assume the use of Key / Token Authentication as the method of access. If you wish to use Cookie Authentication instead, simply drop the apiKey reference from the curl call, and add the cookie option -b cookie.txt to the end of it. For example, the following call to retrieve a Formbird document, can be adjusted as shown below.

Key / Token Authentication example:

curl http://localhost:3000/api/document/dcfc63d0-9442-11e7-a6b2-d9cc8e84f3a6 \
-H "apiKey: bf5b0500-9332-11e6-9c03-853f647fe4a4"

Cookie Authentication example:

curl http://localhost:3000/api/document/dcfc63d0-9442-11e7-a6b2-d9cc8e84f3a6 \
-b cookie.txt