API Reference
Start typing to search…

Authentication Guide

CarePortals uses a token-based authentication system to secure its APIs. To interact with the API, you must first obtain an access token and then include it in the header of all subsequent requests.

This process ensures that only authorized users can access protected resources.

Authentication Flow

Authenticating with the CarePortals API is a straightforward, multi-step process. Our system uses JSON Web Tokens (JWT) for secure communication. Here’s how it works:

  1. Your initial username and password will be securely created and provided to you by the CarePortals team.
  2. You make a POST request to the appropriate authentication endpoint for the API you are using (e.g., /patient/auth for the Patient API). This request must include your credentials in the request body and your organization ID in the organization header.
  3. If the credentials are valid, the API returns a JWT in the response body. You must store this token securely on your server.
📘

For security, JWT access tokens are designed to expire after a certain period. To enhance this process, we are working to introduce refresh tokens in a future release, which will provide a more seamless and secure authentication experience.

  1. For every subsequent request to a protected endpoint, you must include two headers:
  • Authorization: Contains the JWT, prefixed with Bearer.
  • organization: Your unique organization ID.

Storing The Authentication Token

To securely store the authentication token, CarePortals suggests the following options:

  • HttpOnly Cookies (Recommended): This is the best option, and you should use it whenever possible. They are set by the server with HttpOnly flag, cannot be accessed by JavaScript and are automatically sent with every request.
  • Memory Storage: This option is best suited for Single Page Applications, as the token is stored in application state, cleared upon page refresh or logout, and has no persistence to disk.

Best Practices

When working with Token storage, we suggest you always check the following:

  • Never store tokens in localStorage or sessionStorage
  • Use HttpOnly cookies when possible
  • Implement automatic token refresh before expiration
  • Clear tokens immediately on logout
  • Use secure, HTTPS-only connections