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.
Note: Consent is granted at the installation level, not per charger. One installation may include multiple chargers. The redirect URL after consent includes the installationId, but not the specific charger involved.
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
partnerName
will 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=1
Step 5: Handle the Redirect and Access Outcome
After the user completes the access request:
- If no
returnUrl
is set, they will be redirected to Zaptec's default receipt page:/access/receipt/:success?lookup
- If a
returnUrl
is provided, they’ll be redirected there with the following query parameters:success=true|false
installationId=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
installationId
as a parameter in the URL to target the correct installation, since Pro sites often have multiple chargers or shared access setups.
Step 6: Handling Installations with Multiple Chargers
After consent only installationId
is returned. It is key reference point, and it encompasses all chargers under that installation. The Zaptec API does not return a specific charger ID at this point. To identify and link a specific charger, follow this flow:
a. Confirm User Connection
Once the user is redirected with success=true
and the installationId
, consider the user successfully connected at the installation level. You can now skip or hide any general connection screens in your app.
b. Retrieve Installation Details
Use the following endpoint to fetch a breakdown of the installation and its devices:
GET /installations/{installationId}/hierarchy
This will return a list of all chargers associated with the installation.
c. Let the User Choose Their Charger
If multiple chargers are present, display a selection interface so the user can choose the charger they interacted with or want to link. Populate the options using the data returned from the hierarchy API.
d. Save the Serial Number
After the user selects their charger, extract the serial number from the corresponding object in the response and store it in the user’s profile within your system.
## Additional Notes
Users don’t get added to an installation. Instead, they grant access to your UserGroup, and all group members inherit the relevant permissions.
The consent URL must include
installationId
for Zaptec Pro installations due to their shared access and multiple charger setups.Use the
installationtype
parameter to specify installation type:
1
→ Zaptec Go/Home (default)
0
→ Zaptec Pro
Updated 3 days ago