This guide explains how to allow third parties to prompt users to give access to their installations, allowing seamless integration without requiring users to log in each time. This is especially useful when a partner needs to control an installation on behalf of a user. Once granted access, the partner can manage the installation in future integrations.
Using a Lookup Key to request access
Zaptec provides a lookup key that allows partners to prompt users to grant access to their installations.
- The lookup key is linked to a UserGroup and can be found under the Details tab of a UserGroup entry.
- If you do not have access to this section, please contact your Zaptec representative for assistance.
Creating an Access Request URL
Using the lookup key, you can generate a URL to prompt a user for authentication.
URL format:
https://portal.zaptec.com/access/request/<lookup key>
Replace <lookup key> with the actual lookup key from the UserGroup.
This flow currently applies only to Zaptec Home and Zaptec Go installations. If implementing for a Zaptec Pro installation, the installationId must be included in the parameters.
Optional URL Parameters
You can customise the access request by adding parameters to the URL:
| Parameter | Description |
|---|---|
| lookup | The lookup key of the UserGroup requesting permission. The group name will be shown after login. |
| partnerName | The name displayed before the user logs in, indicating who is requesting access. |
| lang | Specifies the language to use for the process. |
| installationId | Pre-selects a specific installation for the access request. |
| installationtype | Allows 0 or 1. Defaults to search for only Zaptec Go (1), but can also be set to 0 to search for Zaptec Pro. |
| returnUrl: | Defines where the user is redirected after the process. If not provided, Zaptec's built-in receipt page is used. |
| success | Indicated whether access was granted (true or false). |
| showExisting | Set to "true" to display all installations the user has access to, even if access was already granted. By default this parameter is "false". |
We do not check UserGroup before login. To ensure clarity, always include the time partnerName when opening the view to make it clear to the user who is requesting access. When the user logs in, the partner name will update to reflect the proper user group name.
Here’s an example of a properly formatted access request URL:https://portal.zaptec.com/access/request/BSJG?partnerName=Integration&lang=en&returnUrl=https://yourapp.com/access-result&installationtype=1
Updated