Third-party integration onboarding flow
This flow enables third-party Integrators to request access to a user's installation via a simple link eliminating the need for the user to manually log in each time. It’s particularly useful when a partner needs ongoing access to monitor or control an installation on behalf of the user.
Requirements:
- Third party should have a usergroup in zaptec portal
- Read through Zaptec API usage guidelines API Usage Guidelines and API Fair Use Policy
Step 1: Retrieve the Lookup Key
- The lookup key is associated with a UserGroup in the Zaptec system.
- You can find it in the Details tab of a UserGroup entry within the Zaptec portal.
- If you don't have access to this section, please reach out to your Zaptec representative.
Step 2: Construct the Access Request URL
Use this format to create the access request link:
https://portal.zaptec.com/access/request/<lookup_key>Replace <lookup_key> with your actual UserGroup's lookup key.
This URL prompts the user to authenticate and grant your UserGroup access to their installation.
Step 3: Share the URL with the User
- Send the generated URL to the end user.
- When the user clicks the link, they’ll be prompted to log in to their Zaptec account.
- After logging in, they'll see a permission request showing the name of your integration or UserGroup.
- Once the user approves the request, your UserGroup will be granted access to their installation.
What Granting Access Means
Once access is granted:
- ✅ All users in the UserGroup will be able to view charge history and installation details.
- ✅ They’ll be able to change installation settings.
- ✅ They can control and configure connected charging stations.
This access allows integration partners to fully manage and support the installation within their workflows or platforms.
Step 4: Customize the Request with URL Parameters
You can tailor the URL using optional query parameters:
| Parameter | Description |
|---|---|
lookup | The lookup key of the requesting UserGroup (required). |
partnerName | Shown before login, to help identify your integration. |
lang | Language code (e.g., en, no) for localization. |
installationId | Preselect a specific installation. Required for Zaptec Pro. |
installationtype | Defaults to 1 (Zaptec Go). Set to 0 for Zaptec Pro. |
returnUrl | Redirect URL after the process is completed. |
success | Returned as a query param in the returnUrl, indicates access result. |
showExisting | Set to "true" to show all installations, even those already shared. Defaults to "false". |
Before the user logs in, only the
partnerNamewill be shown. After login, the actual UserGroup name will replace it in the interface.
Example Access Request URL
https://portal.zaptec.com/access/request/BSJG?partnerName=Integration&lang=en&returnUrl=https://yourapp.com/access-result&installationtype=1Step 5: Handle the Redirect and Access Outcome
After the user completes the access request:
- If no
returnUrlis set, they will be redirected to Zaptec's default receipt page:/access/receipt/:success?lookup - If a
returnUrlis provided, they’ll be redirected there with the following query parameters:success=true|falseinstallationId=xxxxx(if access was granted)
- This flow supports Zaptec Home and Zaptec Go installations.
- For Zaptec Go (or Home), the standard lookup-based URL works directly.
- For Zaptec Pro, you need to include the specific
installationIdas a parameter in the URL to target the correct installation, since Pro sites often have multiple chargers or shared access setups.
Updated 13 days ago