An API Key is used to connect systems. Creating a key generates the connection credentials, but does not define what data the integration transfers or when it runs. Agree on how the connection will be implemented and what it will be used for with the integration administrator.
Permissions and where to manage keys
Managing keys requires Spotilla admin user permissions; manager user permissions are not sufficient. From the main menu in the browser version, open Settings, then the Integrations tab and, under it, API Keys. API Key management is not available in the Android or iOS apps.
The key uses the predefined permissions of the integration account created for it. The form does not let you select a restricted set of permissions. These permissions cover, for example, reading, creating and updating Spots and customer data, as well as handling service requests. Some permissions depend on the features enabled in the service. Provide the key details only to the administrator of that integration, using the agreed method. You do not need to create separate mobile user credentials for this purpose.
Create a key and start using the credentials
- Select Create API Key above the key list.
- Fill in the required Name field. Enter a name of no more than 50 characters that will make the purpose clear later as well.
- Select an Expiry date if needed. Leaving the field empty means that no expiry deadline is set for the key.
- Select Create API Key on the form. The created key appears in the list.
- Open the details by selecting the key's name or the pencil icon on its row. Select Show/hide values on the details form to see the Token, User ID and Subdomain details.
- Provide all three details to the integration administrator to configure the connection. User ID identifies the integration account's user, and Subdomain identifies the Spotilla customer account.
Show/hide values only changes whether the details are visible on the form. It does not change the key or disable it. The credentials cannot be edited directly in these fields.
Other requirements for setting up the integration are covered in How do I check the requirements and status for setting up an integration?
Change the name or expiry date
Open the key's details from the list, change Name or Expiry date, and select Save. Changing the name does not change the credentials. Clearing the expiry date removes the deadline.
The key can no longer be used for authentication once its saved expiry time has passed. Keys past their deadline are also invalidated automatically; invalidation clears the expiry date. An empty date alone therefore does not indicate that the key works.
If use is blocked only because the deadline has passed and the key has not yet been invalidated, moving the deadline into the future or clearing it may restore access. Changing the date does not restore a key that has already been invalidated: in that case, Reset token is required.
Change the key by resetting it
Select Reset token on the key's details form when you need a new key or want to use an invalidated key again. The action changes the key immediately and invalidates the old authentication tokens. An expiry time that has already passed is removed, but a future deadline is retained.
Reopen the details and display the credentials. Update the Token in every connection that uses it. User ID and Subdomain remain the same. Connections using the old key will not continue working simply because the key has been changed in Spotilla.
Invalidate a key or delete the integration account
First check which connections the key serves. Select Set as expired on the details form when the key needs to be disabled immediately. The action invalidates the key, removes its authentication tokens and clears the expiry date. The row and integration account remain. The key can only be used again after it has been reset and the new value has been put into use.
Reset token and Set as expired take effect immediately without a separate save. Closing the form or selecting Cancel does not undo them. These actions do not delete business data that the integration has already created or changed.
If you also want to delete the integration account, select the trash icon on the relevant row in the key list and confirm the deletion. Deletion removes the account, its associated user, the key and authentication tokens, as well as the row from the list. A deleted key cannot be restored by resetting it; creating a new key generates a new integration account and new credentials.
Deleting the account does not undo previous data transfers. The user's messages and comments remain, but their link to the deleted author is removed. References to the user responsible for tasks may also be cleared. Signature requirements associated with the account may prevent deletion; if this happens, investigate the displayed error before trying again.
Verify the result of the change
Reload the key list, for example by refreshing the browser page. Check that the name, expiry date and Status are correct. Not in use means the key has been invalidated. However, In use does not guarantee a working connection: a key past its deadline may appear this way before automatic invalidation. The visibility of the key fields on the details form does not prove that the key is valid either.
Perform the intended connection test in the system that uses the key. After creating or resetting a key, verify that the new credentials work and that the desired action produces the expected result. After a reset, the old key must stop working; after invalidation or deletion, the connection must no longer be able to authenticate with it. If necessary, also check the transferred data in Spotilla and the other system. The key's status alone does not confirm that the data transfer succeeded.