Skip to main content

Salesmsg API: OAuth Apps and HIPAA PHI Access

Set up the OAuth2 authorization flow for your app and get PHI API access for HIPAA organizations.

A
Written by Aaron Sundukovskiy

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

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:

  1. The application opens a browser to send the user to the OAuth server.

  2. The user receives the authorization prompt and approves the application request.

  3. The user is redirected back to the app with the authorization code in the query string.

  4. 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

Response_type

Set to code indicating that you want an authorization code as the response.

Client_id

The identifier for apps. You will find it on the OAuth Applications page.

Redirect_uri

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.

Scope

Stands for the scopes the application is requesting, separated by URL-encoded spaces.

State

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:write

  • messages:read / messages:write

  • calls:read

  • recordings:read / recordings:write

  • contacts:read / contacts:write

  • attachments: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

  1. The integrator (OAuth app owner) reaches out to Salesmsg requesting PHI API access.

  2. Salesmsg sends a BAA to the integrator for signature.

  3. Once the BAA is signed, Salesmsg records the BAA status internally.

  4. 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].

Did this answer your question?