Authentication

The HealthSherpa for Medicare Partner API v2 uses OAuth 2.0 Authorization Code flow for authentication.

Production

Endpoint	URL
Production	Authorization:	https://medicare.healthsherpa.com/oauth/authorize
	Token:	https://medicare.healthsherpa.com/oauth/token
Staging	Authorization:	https://medicare-staging.healthsherpa.com/oauth/authorize
	Token:	https://medicare-staging.healthsherpa.com/oauth/token

1. Redirect User to Authorization Endpoint

Direct the user to:

https://medicare.healthsherpa.com/oauth/authorize?
client_id=YOUR_CLIENT_ID&
redirect_uri=YOUR_REDIRECT_URI&
response_type=code&
scope=partner_api_v2

Parameters:

• client_id (required): Your application's Client ID

• redirect_uri (required): Must match the URIs registered with HealthSherpa

• response_type (required): Always code

• scope (required): partner_api_v2 - grants access to the Partner API v2

2. User Authorizes Your Application

The user will see a consent screen asking to authorize your application. Upon approval, they are redirected to your redirect_uri with an authorization code:

YOUR_REDIRECT_URI?code=AUTH_CODE&state=STATE_VALUE

3. Exchange Authorization Code for Access Token

Your server exchanges the authorization code for an access token:

curl -X POST https://medicare.healthsherpa.com/oauth/token
-H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=authorization_code"
-d "code=AUTH_CODE"
-d "client_id=YOUR_CLIENT_ID"
-d "client_secret=YOUR_CLIENT_SECRET"
-d "redirect_uri=YOUR_REDIRECT_URI"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "partner_api_v2"
}

Parameters:

• access_token: Use this token to make API requests

• token_type: Always Bearer

• expires_in: Token lifetime in seconds

• scope: Granted permissions, always "partner_api_v2"

4. Use the Access Token

Include the access token in the Authorization header of your API requests:

curl https://api.medicare.healthsherpa.com/v2/contacts \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"contact": {"external_id": "CRM123", "first_name": "John", "last_name": "Doe"}}'

5. Refresh Tokens

When your access token expires, use the refresh token to get a new one :

curl -X POST https://medicare.healthsherpa.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "NEW_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "NEW_REFRESH_TOKEN",
  "scope": "partner_api_v2"
}

---

Troubleshooting

Invalid or Expired Token

{
  "error": {
    "message": "The access token is invalid.",
    "code": "invalid_token"
  }
}

Response: 401 Unauthorized

Solution: Obtain a new access token by repeating the OAuth flow.

Missing Authorization Header

{
  "error": {
    "message": "Missing authorization header",
    "code": "missing_authorization"
  }
}

Response: 401 Unauthorized

Solution: Include the Authorization: Bearer YOUR_ACCESS_TOKEN header in all requests.

---

Security Best Practices

• Store Client Secret securely (use environment variables or secrets management)

• Use HTTPS for all requests

• Validate redirect URIs

• Rotate access tokens regularly

• Use short-lived access tokens

• Store tokens securely on your backend (never in frontend code)