Use OAuth2 when you want other Salesmsg users to authorize your app. This article covers the OAuth2 URLs, the authorization code grant flow, and the extra steps a HIPAA organization needs before an OAuth app can access PHI-sensitive data.
Authorize an OAuth App
OAuth2 URLs
URL | Description |
Base authorization URL | |
Token URL |
1. Authorization code grant flow
The authorization code grant flow is most suitable for web and mobile applications. It differs from the other grant types by requiring the application to launch a browser first to begin the integration.
The integration consists of the following steps:
The application opens a browser to send the user to the OAuth server.
The user receives the authorization prompt and approves the application request.
The user is redirected back to the app with the authorization code in the query string.
The application exchanges the authorization code for an access token.
Below, you can find the description of the authorization code grant flow in detail.
Get user permission
The application sends the user to a browser to get their permission. To begin the authorization flow, the application constructs an URL like the following and opens a browser to that URL:
https://app.salesmessage.com/auth/oauth?response_type=code&client_id=269&redirect_uri=https://example.app/callback&scope={ADD_NEW_SCOPES_HERE}&state=xcoiv98y2kd22vusuye3kch
Hereâs each query parameter explained:
Parameter | Description |
| Set to code indicating that you want an authorization code as the response. |
| The identifier for apps. You will find it on the OAuth Applications page. |
| Used to redirect to after the user is granted permission or denied permission. The URI needs to have been entered in the Redirect URI field that the user specified at creating the application. |
| Stands for the scopes the application is requesting, separated by URL-encoded spaces. |
| A value included in the request, which is also returned in the token response. It can be a string of any content that you wish. A randomly generated unique value is typically used for preventing cross-site request forgery attacks. |
HIPAA Organizations: Additional Requirements
If your Salesmsg organization has HIPAA enabled, there are extra steps required before a third-party integration (OAuth app) can access PHI-sensitive data through the API.
What is PHI-sensitive data?
The following scopes access Protected Health Information (PHI) and are subject to HIPAA rules:
conversations:read / conversations:writemessages:read / messages:writecalls:readrecordings:read / recordings:writecontacts:read / contacts:writeattachments:read / attachments:write
Business Associate Agreement (BAA) Requirement
Before any third-party OAuth integration can access PHI-sensitive endpoints in a HIPAA organization, a signed Business Associate Agreement (BAA) must be on file between Salesmsg and that integrator.
Important: The BAA your organization has with Salesmsg does not automatically cover third-party integrators. Each OAuth application that needs to access PHI requires its own separate BAA.
What happens without a signed BAA:
The integrator's token request will be blocked with
HTTP 403: "Access denied. You must have a signed Business Associate Agreement (BAA) to continue."
Note: This BAA requirement applies to third-party integrators only. Organization members accessing their own data directly via PAT are not affected.
How to Enable PHI API Access for a HIPAA Org
The integrator (OAuth app owner) reaches out to Salesmsg requesting PHI API access.
Salesmsg sends a BAA to the integrator for signature.
Once the BAA is signed, Salesmsg records the BAA status internally.
The integrator can now obtain OAuth tokens and access PHI-sensitive endpoints.
To get started, contact [email protected] or reach out via live chat.
Frequently Asked Questions
I'm on a HIPAA plan. Can I use the API?
Yes. HIPAA organizations can use the Public API and OAuth integrations. However, any third-party OAuth application that needs to access PHI-sensitive endpoints (messages, conversations, contacts notes, calls, attachments, recordings) must have a signed BAA with Salesmsg before access is granted. Contact [email protected] to get started.
Does the BAA requirement apply to my own Personal Access Token?
No. This BAA requirement applies to third-party integrators only. Organization members accessing their own data directly via PAT are not affected.
Related Articles
Need Help? âđ»
Contact us on live chat or send an email to us at [email protected].

