Tips & Tricks for Integrations and API Keys
To give an integration access to Yesplan you must Create an API Key. However, there are various ways to deal with integrations and API Keys. You will find a few tips on this page.
An API key is actually a password for an API:
- Everyone with the API key will have access to your API, as well as the information in your installation, and they can even edit fields depending on how the permissions are set. Therefore, take as much care with the key as you would with a password, and do not publish it publicly.
- Do not create an API key for a user who is an administrator.
- Do not share keys with anyone else (other than the creator of your integration).
- Delete an API key if you suspect that it has been leaked.
- Think twice before you delete an API key: if it is being used by an integration, that integration will no longer function correctly. In that case, create a new API key for the integration immediately, and pass the new key on to the developer of the integration.
Users for API Keys§
You can create an API key for any Yesplan user, but you will need to remember that the key for a given integration is associated with a specific user:
- If you delete the user the integration will no longer have access to Yesplan.
- You must make sure that the permissions for both the user and the integration are set correctly.
- The user must not be made an administrator.
For that reason we advise you to create a specific user for every integration, to be used for that integration only. This will prevent you from accidentally deleting a user or making a user an administrator, and it will ensure that you apply the correct permissions for every integration. To do this, carry out the following steps.
Create a new user and assign the correct permission templates:
Go to “System Settings” > “Users” > “Users”.
Click “Add a User” at the bottom and fill in the fields:
- Username: the (company) name for your integration, e.g. “Website”
- Password: Yesplan helps you choose a strong password
- Name: the (company) name for your integration, e.g. “Website”
- Email: enter nothing here as this user will only be used for the integration
- Create a linked resource: select this checkbox
- Create a linked contact: deselect this checkbox.
As this user is only used for the integration’s API key, there is no point in linking a contact.
Once you have created the user, you change the settings:
- User Groups: optional
- Primary User Group: optional
- Permission Templates:
- “Common” or “General”, depending on your installation
- Administrator: must not be selected.
- You can also create a user group for this user, or assign him to an existing user group if this is the method you use in your installation. But it is not necessary.
- We strongly advise against giving integrations access via a user who is an administrator.
Assign permissions to the user for the integration.
- Go to “System Settings” > “Users” > “Permission Templates”.
- Click on “Show permissions” for the general template. Often, it will have the name “General” or “Common”. It is the template that determines which permissions are assigned to user groups.
- Click on “Add User Group or User” at the bottom, choose the user you have just created (or the user group to which he belongs), and click “Add”.
- In this row select only the permissions that are needed by the integration:
- Does the integration need to fetch but not edit events, for example? In that case, select only “View” under events.
- Does the integration need to fetch and edit resources, for example? In that case, select “View” and “Edit” under resources.
Every integration has different permission requirements. If necessary, consult your integration’s creator or your Yesplan Customer Success Manager to find out exactly what permissions the integration needs.
Hiding Linked Resources§
When you create a user, a resource with the same name is created automatically. As this user is only used for the integration’s API key, it is best to hide the linked resource to prevent it from being booked:
- Click on “Resources” in the navigation menu.
- In the search bar, search for the name of the user that you have just created. This was “Website” in our example.
- In the search results right-click on the correct resource and choose “Show Info”.
- Under the “Permissions” tab deselect all checkboxes in the “View” column.
Administrators always see all resources, even if the “View” permission has been deselected for some of them.
Creating API Key§
To access the API you will need to create an API key in Yesplan and pass it on to the creator of the integration.
- Go to “System Settings” > “Integrations” > “API Keys”.
- Choose the user that you have just created (e.g. “Website”) from the drop-down menu under the table and click “Add”.
- The user will be added to the table. The value in the “Key” column is the API key with which the integration accesses the Yesplan API.
See Creating an API Key for more information.
Tab for Your Integration§
Your integration will continue to work perfectly if you don’t carry out this step, but we recommend that you create a tab for all the custom data fields used by the integration. This will give you a nice overview in Yesplan of the data, per event and resource, used by an external integration.