This article is outlining how to allow third parties to prompt users to give access to their installations.
This will then bypass the need for a user to log in each time.
This is typically used when a partner wishes to control an installation on behalf of the user, ensuring they are granted access on the users installation. This can then be used to control the installation in a future integration.
Lookup Key
We offer the ability to prompt a user to allow third parties access to their installation based on a lookup key.
The lookup key is associated with a UserGroup in our system and can be found under the Details tab of a UserGroup entry.
If you do not have access to this screen, please contact your Zaptec representative and they can advise you of your lookup key.
Using this lookup key, you can create a URL to use to prompt a user to authenticate.
The base URL for this: https://portal.zaptec.com/#!/access/request/
Using this flow will currently only work for Installation Type Home or Go.
If you want to build this for a Pro installation, the InstallationId should be included in the parameters.
Parameters
See optional parameters listed below:
You can add parameters like lang and returnUrl if you need / want to specify this for your integration.
lookup: the lookup key of the group asking for permission. After logging in the group name is shown as the permission requester.
partnerName: the name to show as permission requested before the user has logged in and we’re able to show the proper group name.
lang: the language to use for the process
installationId: preselects an access request to the single installationId given in the URL
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: the URL to return to after completing the process, if not provided we’ll redirect to the built in receipt page: / access / receipt /: success? lookup. Parameters added to the redirect URL:
- success: true / false whether access was granted or not.
- installationId: if access was granted, the ID of the installation granted access to
showExisting: Setting this to "true" will display all installations the user has access to, even though the user group already has access to the installation. It is possible to redo the access grant on an installation the user group already have access to.
By default this parameter is false.
We do not lookup user groups before the user logs in, partnerName should be provided 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.
Example
https://portal.zaptec.com/#!/access/request/BSJG?partnerName=Integration