JWT Authentication

GeckoForm uses JSON Web Tokens for API authentication.


Getting a JWT

Generating A New API Token

You can manage your API tokens from the Security Preferences.
  1. In GeckoForm tap on your name in the upper right corner
  2. Select "Security Preferences" from the drop down
  3. View your current logins from the "Active Sessions" section

From here you can see all your active sessions and any previously created API tokens.

  1. Tap "Create New API Token
  2. Give your new token a descriptive name so you can identify it in the future
  3. Select the profile that you wish to generate API access for and continue to the next step
  4. Finally grant your new API token permissions. You should only grant the neccessary permissions required for the task your API token will be carrying out.
    • You can quickly find permissions by using the search bar to filter the list
  5. Once you have choosen the neccessary permissions for your new token tap "Create"

Your new token should now appear in your list of active sessions. From here you can copy your Access, ID and Refresh tokens into your application.

Using your JWT

The JWT comes in three parts: ID, Access and Refresh. To access GeckoForm API resources the ID part should be passed up via the Authorization header, prefixed with 'Bearer '. For example:

curl 'https://api-eu.geckoform.com/forms?per_page=15'
    -H 'Accept: application/json'
    -H 'Authorization: Bearer eyJ0eXAiOi...SJVshYBNjP25g' # ID Token

Refreshing the token

JWT are valid for a fixed amount of time (generally 1 day for API tokens), after which a new JWT must be obtained using the Refresh token, the Refresh token will also expire (generally after 30 days for API tokens).

When the JWT is refreshed all three parts will be regenerated with new expiry times. If the token is not refreshed before the refresh token expires a new token must be requested. The tokens can be refreshed at any time before the refresh token expires which will not invalidate existing tokens, allow the tokens to be refresh early to ensure uninterupted API access.

curl 'https://account-api.geckoengage.com/tokens/refresh'
    -H 'Accept: application/json'
    -H 'Authorization: Bearer eyJ0eXAiOi...SJVshYBNjP25g' # Refresh Token