> For the complete documentation index, see [llms.txt](https://docs.medicare.healthsherpa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.medicare.healthsherpa.com/api-reference/version-2-oauth/authentication.md).

# Authentication

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

**Production**

<table><thead><tr><th width="109.37890625">Endpoint</th><th width="131.421875">URL</th><th width="559.421875"></th></tr></thead><tbody><tr><td>Production</td><td>Authorization:</td><td><code>https://medicare.healthsherpa.com/oauth/authorize</code></td></tr><tr><td> </td><td>Token: </td><td><code>https://medicare.healthsherpa.com/oauth/token</code></td></tr><tr><td>Staging</td><td>Authorization:</td><td><code>https://medicare-staging.healthsherpa.com/oauth/authorize</code></td></tr><tr><td></td><td>Token: </td><td><code>https://medicare-staging.healthsherpa.com/oauth/token</code></td></tr></tbody></table>

### 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,
  "refresh_token": "def50200b7a9c3e4f1d2a6b8c9e0f123456789abcdef...",
  "scope": "partner_api_v2"
}
```

**Parameters**:

* `access_token`: Use this token to make API requests
* `token_type`: Always Bearer
* `expires_in`: Token lifetime in seconds, applies to the access token
* `refresh_token`: Use this token to obtain a new access token
* `scope`: Granted permissions, always "partner\_api\_v2"

### **4. Use the Access Token**

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

{% code overflow="wrap" %}

```bash
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"}}'
```

{% endcode %}

### 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"
}
```

Refresh tokens are rotated: when refreshing, store the newly returned `refresh_token` and discard the previous one.

***

### 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)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.medicare.healthsherpa.com/api-reference/version-2-oauth/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.