The OAuth API for the CRM Marketplace offers developers two types of access: Location Level Access (also known as Sub-Account) and Agency Level Access (also known as Company). These access levels provide comprehensive control over location data at either the individual location or agency-wide level. With Location Level Access, developers can perform operations specific to a sub-account, while Agency Level Access enables them to manage data across the entire agency. This distinction ensures efficient data handling and enhanced CRM Marketplace API v2.0 interoperability.
Developer Support Link: https://developers.gohighlevel.com/support
Always provide all the details and a loom video if you can while creating a support ticket for developers.
Covered in this Article
Glossary of terms:
- AppID - This is the unique identifier for your marketplace application. You can find it below the app name.
Conversation Provider ID - This is the unique identifier for the type of provider a user installs. You can find it under the name of the conversation provider name if you have created conversation providers for your app.
What is the OAuth Flow in the Developer's Marketplace?
The GitHub Repository mentioned in the video is accessible here.
Gohighlevel Developers Marketplace
Gohighlevel Developers Community
The OAuth Flow in the Developer's Marketplace typically consists of the following steps:
App Registration: Developers register their applications on the Developer's Marketplace, providing necessary details and defining scopes. They receive a Client ID and a Client Secret, unique identifiers for their application.
Authorization Request: The application directs the user (usually via a browser) to the Marketplace's authorization server. The authorization request includes the Client ID, the requested scopes, and a redirect URL, a location in the application where users will be sent after authorization.
User Consent: The user logs into the Marketplace and reviews the application's request to access specific details (as defined by the scopes). If the user agrees, they are redirected to the provided redirect URL, with an authorization code appended as a query parameter.
Authorization Grant: The application receives the authorization code and verifies it. The application then makes a POST request to the authorization server, including the authorization code, Client ID, and Client Secret.
Access Token Issuance: If all the submitted details are correct and the authorization code is valid, the authorization server issues an access token to the application. The application can now use this access token to make requests to the API on behalf of the user, limited to the scopes defined earlier.
API Call: The application includes the access token in the header when making API calls. The server allows the requested operation if the access token is valid and has the necessary scopes.
Token Refresh: Access tokens have a limited lifetime and must be periodically refreshed using a refresh token (if provided by the authorization server). The application requests the server with the refresh token; a new access token is issued if it's valid.
Remember, OAuth is a delegation protocol, handy in scenarios where the application must act on users' behalf without requiring users' credentials. The actual flow might vary slightly based on the implementation of the Marketplace, but the basic principles remain the same.
- Managing Contacts: Use the contact management APIs to create, update, search, and delete contacts, enabling efficient customer relationship management.
- Conversations Management: Implement the Conversations API to retrieve, update, and delete conversations, allowing for streamlined customer communication.
- Message Automation: Leverage the messaging APIs to send and schedule automated email and SMS messages, enhancing customer engagement and lead nurturing.
- Form Submissions: Implement the forms APIs to capture and manage form submissions, enabling lead generation and data collection.
- Link Management: Use the links API to create, update, and delete links, allowing for effective tracking and management of URL links.
- Location Tagging: Utilize the location tags APIs to assign and manage tags for different locations, facilitating organized categorization and filtering.
- Custom Field Management: Implement the custom fields APIs to create, update, and delete custom fields, enabling flexible data organization and customization.
- Custom Value Management: Use the custom values APIs to create, update, and delete custom values associated with contacts, enhancing data personalization.
- Template Management: Leverage the email and SMS template APIs to create, retrieve, and update templates, facilitating consistent and efficient messaging.
- Opportunity Management: Utilize the opportunities APIs to create, update, and delete opportunities, enabling effective sales pipeline management.
- Note Creation: Implement the create note API to add notes to customer profiles, facilitating easy documentation and information sharing.
- Task Management: Use the task APIs to create, update, and delete tasks, enabling efficient task tracking and workflow management.
- Appointment Scheduling: Leverage the appointment APIs to create and update appointments, facilitating easy scheduling and calendar management.
- Order Processing: Utilize the order APIs to create, update, and manage customer orders, streamlining the order fulfillment process.
- Customer Management: Implement the customer APIs to create, update, and delete customer profiles, facilitating comprehensive customer relationship management.
- User Management: Use the user APIs to create, update, and delete user accounts, facilitating user administration and access control.
- Workflow Automation: Leverage the workflow APIs to create, update, and delete workflows, enabling automated business processes and task automation.
- Snapshot Retrieval: Utilize the snapshot APIs to retrieve and manage snapshots of data, allowing for historical data analysis and reporting.
These usage cases demonstrate how the developer marketplace's APIs can be applied in various practical scenarios to enhance productivity, automate processes, and optimize business operations.
How to use the oAuth V2 to configure Webhooks for your apps?
To configure webhooks for your application, follow these steps:
Step 1: Sign up for a developer account
Go to https://marketplace.gohighlevel.com and sign up for a developer account if you haven't already.
Step 2: Create an app
After signing in, go to "My Apps" and click "Create App" to create a new app.
Step 3: Fill in the profile information
Fill in all the required profile information for your app.
Make sure to mark the app as public.
The "App Name" refers to the name or title given to your application. It is a unique identifier representing your app within the developer marketplace and helps users quickly identify and distinguish it from other apps.
App Type: Public, Private:
The "App Type" determines the accessibility and visibility of your application.
Public App: A public app is available for anyone to use and access. It is listed in the developer marketplace and can be installed by users with the necessary permissions.
Private App: A private app is restricted to a specific group or individuals. It is not publicly listed in the Marketplace and requires an invitation or authorization to access and use.
Distribution Type: Agency, Sub Account:
The "Distribution Type" specifies how your app is distributed and made available to users.
Agency Distribution: If you choose the agency distribution type, your app will be accessible to all accounts. This means that all agency members or sub-accounts can install and use the app. All
Sub-Account Distribution: With the sub-account distribution type, your app is limited to a specific sub-account within your agency. Only users belonging to that particular sub-account can install and use the app.
Step 4: Add scopes
In the app settings, add the required scopes for your app.
Refer to the documentation (https://highlevel.stoplight.io/docs/integrations/6444956c5219f-scopes) to determine the necessary scopes.
Step 5: Generate client credentials
Create a client key for your app.
Save the generated Client ID and Client Secret, as needed, in the next steps.
Step 6: Set up the OAuth endpoint
Create a GET endpoint in your application that will handle the OAuth process.
Refer to the documentation (https://highlevel.stoplight.io/docs/integrations/00d0c0ecaa369-get-access-token) for more details on how to obtain the access token.
To create a GET endpoint for OAuth in your application:
- Choose a route for your endpoint (e.g., "/OAuth/callback/gohighlevel").
- Configure your application to listen for requests to this route.
- When a user authorizes your application, GoHighLevel will redirect them to your endpoint with a "code" parameter.
- Retrieve the "code" parameter from the request.
- Store the code securely.
- Make a POST request to GoHighLevel's "/OAuth/token" endpoint with the code, client ID, client secret, grant type, and redirect URI.
- Capture the response from the POST request.
- Extract the access token, token type, expiration time, refresh token, and other relevant information from the response.
- Store the access token securely in your application.
You can now use the access token to authenticate GoHighLevel API requests.
Following these steps, your GET endpoint will handle the OAuth process by exchanging the code for an access token and securely storing it for future API interactions.
Step 7: Configure OAuth settings
Set the OAuthToken Redirect URL in your app settings to the endpoint created in the previous step.
Step 8: Create a webhook endpoint
Create a POST endpoint in your application to receive and process webhook events.
This endpoint should be able to handle the JSON body of the event.
Step 9: Set up webhook URL
Enter the URL of your webhook endpoint in the app settings.
Step 10: Assign locations/accounts to your app
Sign into an agency administrator account.
Open a new browser tab and go to your app in the Marketplace.
Click "+ Add App" and search for/select the desired account/location to add the webhook.
Step 11: Retrieve the authorization code
After successfully adding the app, you will be redirected to the Marketplace App page with an updated URL.
Copy the query string parameter "code" from the URL (e.g., code=c40216d8574eb90abe0c884058fa9f5101085exx).
Step 12: Open a new browser tab
Open a new browser tab and enter the following URL: YOUR_REDIRECT_URL?code=CODE
Replace YOUR_REDIRECT_URL with your app's redirect URL and CODE with the authorization code copied in the previous step.
Step 13: Verify webhook connection
If the response from https://services.leadconnectorhq.com/oauth/token was successful and you received the access token, the webhooks should now be connected.
By following these steps, you should be able to configure webhooks for your application and connect them to the desired accounts/locations. Refer to the documentation provided for detailed information on each step.
Q: What is the Developer Marketplace?
A: The Developer Marketplace is a platform provided by HighLevel where developers can create and distribute their custom applications and integrations for use with the HighLevel CRM.
Q: How do I sign up for a developer account on the Marketplace?
A: To sign up for a developer account on Marketplace, go to the website (https://marketplace.gohighlevel.com) and click the sign-up button. Follow the prompts to create your account.
Q: What are scopes in the context of app settings?
A: Scopes define the permissions and access levels your app requires to interact with the HighLevel CRM. You need to add the appropriate scopes to your app settings based on the functionalities your app needs.
Q: How do I generate client credentials for my app?
A: In the app settings, there is an option to generate client credentials. Click on it, and you will receive a Client ID and Client Secret that you can use for authentication and authorization purposes.
Q: Can you explain the process of OAuth with a custom application?
A: OAuth is a protocol for secure authorization between your custom application and the HighLevel CRM. You must create a GET endpoint in your application to handle the OAuth process. This endpoint will receive a code parameter, which you will use to request an access token from the HighLevel API.
Q: What is the purpose of the OAuthToken Redirect URL?
A: The OAuthToken Redirect URL is the endpoint in your application where the access token will be sent after the OAuth process is completed successfully. It should be defined in your app settings.
Q: How can I create a webhook endpoint for my application?
A: To create a webhook endpoint, you must set up a POST endpoint in your application to receive and process JSON payloads sent by the HighLevel CRM. This endpoint will handle webhook events and trigger the necessary actions in your app.
Q: How do I assign locations/accounts to my marketplace app?
A: You can assign locations/accounts to your marketplace app as an agency administrator. Open the app in the Marketplace, click on "+ Add App," search for the desired account/location, and select it to establish the webhook connection.
Q: What is the purpose of the authorization code in the webhook connection process?
A: The authorization code is a unique code generated during the webhook connection process. It is a temporary authorization token exchanged for an access token, allowing your app to interact with the HighLevel API securely.
Q: How can I verify the webhook connection?
A: After completing the webhook connection process and receiving the access token, you can verify the connection by testing your webhook endpoint. Trigger a test event in the HighLevel CRM and check if your endpoint receives and processes the event correctly.
Q: Can I create multiple apps on the Developer Marketplace?
A: Yes, you can create multiple apps on the Developer Marketplace. Each app can have its own unique profile, settings, and webhook configurations.
Q: Is there a limit to the number of scopes I can add to my app?
A: There is no specific limit to the number of scopes you can add to your app. However, it is recommended only to include the necessary scopes that your app requires to minimize unnecessary permissions and improve security.
Q: How often should I update my app's profile information?
A: Keeping your app's profile information current is a good practice. If any significant changes to your app, such as new features or improvements, update the profile to provide accurate information to potential users.
Q: Can I access user data through the Developer Marketplace?
A: You can access user data through the Developer Marketplace by utilizing the appropriate scopes and APIs provided by the HighLevel CRM. However, handling user data responsibly and complying with relevant data protection regulations is essential.
Q: Can I integrate third-party services with my app on the Developer Marketplace?
A: Yes, you can integrate third-party services with your app on the Developer Marketplace. As long as the integration adheres to the platform's guidelines and the necessary APIs or webhooks are available, you can enhance the functionality of your app by connecting it with external services.