Guides
Start typing to search…

Third-party integration onboarding flow

This flow enables third-party partners 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

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:

ParameterDescription
lookupThe lookup key of the requesting UserGroup (required).
partnerNameShown before login, to help identify your integration.
langLanguage code (e.g., en, no) for localization.
installationIdPreselect a specific installation. Required for Zaptec Pro.
installationtypeDefaults to 1 (Zaptec Go). Set to 0 for Zaptec Pro.
returnUrlRedirect URL after the process is completed.
successReturned as a query param in the returnUrl, indicates access result.
showExistingSet 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.

Updated 5 days ago