Skip to content

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.

Security§

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 don’t publish it publicly.
  • Don’t create an API key for a user who is an administrator.
  • Don’t 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’s 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.

Warning

API keys are actually passwords and are therefore strictly personal. After all, any person with one of these keys can access Yesplan via the API.

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 that you create a specific user for every integration, that you use 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.

Creating User§

Create a new user and assign the correct permission templates:

  • Go to “System Settings” > “Users” > “Users” and click “Add user…” at the top right. We advise using the (company) name of your integration for this user.
  • Once you have created the user, you can change the settings:
    • User Groups: Optional.
    • Primary User Group: Optional.
    • Permission Templates: ‘Common’ or ‘General’, depending on your installation.
    • Administrator: Must not be selected.

Tip

  • 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. However, this isn’t necessary.
  • We strongly advise against giving integrations access via a user who is an administrator.

Assigning Permissions§

Assign permissions to the user for the integration.

  • Go to “System Settings” > “Users” > “Permission Templates”.
  • Click “Show permissions” for the general template. Often, it will have the name ‘General’ or ‘Common’. It’s the template that determines which permissions are assigned to user groups.
  • Click “Add User Group or User” at the bottom, choose the user you’ve 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.

Tip

Every integration has different permission requirements. If necessary, consult your integration’s creator or your Yesplan Customer Success Manager to find out exactly which 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’s best to hide the linked resource to prevent it from being booked:

  • Click “Resources” in the navigation menu.
  • In the search bar, search for the name of the user that you’ve just created. This was ‘Website’ in our example.
  • In the search results, right-click the correct resource and choose “Show Info”.
  • Under the “Permissions” tab, deselect all checkboxes in the “View” column.

Remark

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:

  1. Go to “System Settings” > “Integrations” > “API Keys”.
  2. Choose the user that you’ve just created (e.g. ‘Website’) from the drop-down menu under the table and click “Add”.
  3. 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.

Tip

See Managing API Keys 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.

Tip

Read more about: