API keys are a simple encrypted string that can be used to generate a bearer token, that will in turn be used to call GW Apps APIs related to your domain. Make sure that you keep all your keys secure. Publicly exposing your credentials can result in your data being compromised.
| Platform API Keys |
 |
| Item | Description |
| + Create API Key | Click on to create an API Key and select the scopes for Users and Shared roles. |
| Enabled | Allows the specific API key to be enabled or disabled. When it is disabled, requests using that key will be ignored by GW Apps. |
 | Select the three dots to view options for the selected key. |
 | – Generate New Key will generate a new API key. This will invalidate the prior key, so you will need to share the new key with developers of services that access this API. – API Referencewill open the API documentation on how to call the RESTful API endpoints for User and Shared Role actions. – Edit opens the selected API Key configuration for editing. – Remove Deletes the selected API Key configuration. |
API Key Configuration
| Item | Description |
| Name | Name of the API Key. |
| Description | [Optional] Description of the API Key. |
| Security Details | |
| Type | Select ‘All domain users’ to allow anybody to execute an API call, or ‘Specific users’ to allow only specific people access to the API key. |
| User email | Search email address of users within the domain to grant them access to use this API Key. (Hidden if ‘All domain users’ is selected for Type.) |
| Access Details | |
| Entities | Select ‘Users’ or ‘Shared Roles’. (When a new API Key is created, both entities are already listed under Access Details.) |
| Selection Scopes | Sets the scope or permissions allowed for the records for the selected form. Options for ‘Users’ are: – Create User – Suspend User – Activate User – View and Search Users – Export Records to PDF – View Form Options for ‘Shared Roles’ are: – Create Shared Role – Update Shared Role – Delete Shared Role – View and Search Shared Roles – Add User to Shared Role – Remove User from Shared Role (When a new API Key is created, each entity will have all Scopes enabled. You can deselect Scopes to disable the permission,) |
API Key Configuration Best Practices
API keys are a simple encrypted string that can be used to generate a bearer token, that will in turn be used to call your GW Apps APIs. Make sure to keep all your API keys secure. Publicly exposing your credentials can result in your data being compromised.
While generating your API Keys, keep the following suggestions in mind:
- Restrict your API keys to allow only specific email addresses: We recommend creating API Keys using the ‘Select users’ Type, and then selecting only the email addresses of users you want to access records via the API. The API will retrieve data based on the selected user(s) that the token was generated with, so the API will only have access to the same data in this app that the selected user(s) have access to. You can also select ‘All domain users’ which will allow you to act as any user in GW Apps, and hence have full access to all data for the listed forms.
- Restrict your API keys to be usable only for certain forms & scopes: Select what forms and what scopes your API Key has access to. Doing that will limit the level of access that this API Key has. Note: A scope just defines what actions an API call is allowed to make, it does not grant access to any data for the selected users, or all users if ‘All domain users’ is selected for the Type. The normal user access security applies to all API calls. This means that if the ‘Record Create’ scope is enabled, if the user that is calling the API doesn’t have rights to create records (‘Who can Create New Records’ on the form’s Settings tab), the API will return a 401 unauthorized error.
- Regenerate your API keys periodically: You can regenerate API keys from the API Key list page by clicking `Generate new key` for each key. Then, update your applications to use the newly-generated keys. This way, even if an API key is found by unwanted users it will become invalid after a period because a new key was generated.
- Enable / Disable API Keys: You can disable your API key at any time, that will disable any call trying to use that API Key.
- Delete unneeded API keys: To minimize your exposure to attack, delete any API keys that you no longer need.
Additional API Settings
This article covers platform level API options. Additional options for API Keys can be found within documentation for the in-app API options. Learn more about adding keys to your applications here.