Authentication overview
This guide will show how to configure your application to access the Capable Health API. We provide an authentication SDK to facilitate the process.
If you’re building a client-side app (e.g., mobile or web application), see our client-side guide.
If you have a server-side app, see our server-side guide. (Please note: If you’re building a single-page application (SPA) and using a server-side backend, you can choose between our client-side and server-side authentication options based on your needs.)
If you already have an authentication system, see our server-side impersonation guide.
Authentication SDK: Initial configuration
To use the Capable Health authentication SDK, you’ll need a configuration token, which you can retrieve from the API credentials page in your developer portal. The token labeled "End user login" should be used for email-password authentication, a.k.a. the credentials flow.
Authentication SDK: Installation
npm i @capable-health/capable-auth-sdk
Client-side authentication
Below, we show how to configure a mobile or web application to access the Capable Health API.
We currently offer two flows for registering and authenticating end-users of your app with Capable:
passwordless- With our
passwordlessoption, a user can sign in using only their phone number. Upon signing in, a one-time verification code is sent to the user’s phone to confirm their sign-in attempt. - If you’re building a mobile app, or if your traffic is primarily on mobile devices, we highly recommend considering the passwordless flow. In general, the passwordless option can reduce friction in your user signup and login flows, potentially improving conversion.
- With our
credentials- With the
credentialsflow, a user can sign in using an email and password combination. Please note: When using this flow, a verification code will be sent to the user’s email address after they sign up, to confirm their identity. The user must submit the verification code before they can sign in for the first time.
- With the
Client-side authentication: Passwordless flow
To use the passwordless flow, you must configure the SDK at run time before making subsequent calls via the SDK or to the Capable Health API. You can retrieve the CONFIGURATION_TOKEN labeled "Passwordless" from the API credentials page in your developer portal.
import capableAuthSDK from "@capable-health/capable-auth-sdk";
capableAuthSDK.passwordless.configure("<CONFIGURATION_TOKEN>");
Passwordless flow: Signup
To sign up a user with the passwordless flow, you must submit a valid US phone number for the user.
Phone number format
Please note that users’ phone numbers will be normalized after submission to the E.164 format (e.g., +15551234567).
An optional second parameter is available for passing additional attributes to the Patient record being created. The attributes parameter, if used, should be a JavaScript object. In the attributes object, you can pass any of the parameters available on the PATCH /patients/{id} endpoint. (By default, the phone number will be added to the Patient record — you don’t need to include the phone number separately in the attributes parameter.)
import capableAuthSDK from "@capable-health/capable-auth-sdk";
await capableAuthSDK.passwordless.signUp(phone_number, attributes);
Passwordless flow: Sign-in
After the user has been signed up, you can sign them in:
import capableAuthSDK from "@capable-health/capable-auth-sdk";
const user = await capableAuthSDK.passwordless.signIn(phone_number);
// When the user signs in, they will receive an SMS with a verification code.
// This verification code must be passed to the function below to complete
// the sign-in process.
await capableAuthSDK.passwordless.confirmSignIn(user, verification_code);
Client-side authentication: Credentials flow
To use the credentials flow, you must configure the SDK at run time before making subsequent calls via the SDK or to the Capable Health API. You can retrieve the CONFIGURATION_TOKEN labeled "End user login" from the API credentials page in your developer portal.
import capableAuthSDK from "@capable-health/capable-auth-sdk";
capableAuthSDK.credentials.configure("<CONFIGURATION_TOKEN>");
Credentials flow: Signup
With the credentials flow, a user can enter an email and password to sign up.
An optional third parameter is available for passing additional attributes to the Patient record being created. The attributes parameter, if used, should be a JavaScript object. In the attributes object, you can pass any of the parameters available on the PATCH /patients/{id} endpoint. (By default, the user’s email will be added to the Patient record — you don’t need to include the email separately in the attributes parameter.)
After signing up, a verification code will be sent to the user’s email address. The user will need to submit the verification code to confirm their identity before they can sign in to access Capable Health resources.
import capableAuthSDK from "@capable-health/capable-auth-sdk";
await capableAuthSDK.credentials.signUp(email, password, attributes);
// Once the user is signed up,
// they will receive an email with a verification code.
// This verification code must be passed to the following function in order
// to confirm the sign up.
// If not, the user will not be able to make API calls to the Capable Health API.
await capableAuthSDK.credentials.confirmSignUp(email, verification_code);
Credentials flow: Invitation
Patients can be invited to Capable Health using our /patients/invite endpoint, initiating signup on their behalf. (If you’re interested in using our /patients/invite endpoint, please contact us for more information.)
When a Patient is invited with the credentials flow, an invitation email will be sent to the user. The email will contain a temporary password and a link to redirect the user to complete the invitation. The user will need to submit the temporary password and set a new password. This flow will also automatically sign in the user.
import capableAuthSDK from "@capable-health/capable-auth-sdk";
await capableAuthSDK.credentials.completeInvitationAndSetPassword(
email,
temp_password,
new_password,
);
Credentials flow: Password requirements
When using the credentials flow, a user’s password must meet the following requirements:
Credentials flow: Sign-in
If the user has been signed up and confirmed, they are now able to sign in.
import capableAuthSDK from "@capable-health/capable-auth-sdk";
await capableAuthSDK.credentials.signIn(email, password);
Client-side authentication: Signed-in users
Once a user is signed in, whether using the credentials or passwordless flow, the user will be able to perform certain actions. If the user is not signed in, these functions will throw an error.
Signed-in users: Sign out
import capableAuthSDK from "@capable-health/capable-auth-sdk";
await capableAuthSDK.user.signOut();
Signed-in users: Get access token
import capableAuthSDK from "@capable-health/capable-auth-sdk";
await capableAuthSDK.user.getAccessToken();
Access tokens expire after 60 minutes. After this time, you will need to call this function to retrieve a new access token. You have 30 days to retrieve a new access token. After this time, the user must sign back in to fetch a new access token.
Signed-in users: Get user payload
import capableAuthSDK from "@capable-health/capable-auth-sdk";
await capableAuthSDK.user.getPayload();
Each user payload contains information about the user:
{
email: string;
emailVerified: boolean;
groups: string[];
phoneNumber: string;
phoneNumberVerified: boolean;
tenantId: string;
username: string;
userId: string;
userType: string;
}
Signed-in users: Update email
import capableAuthSDK from "@capable-health/capable-auth-sdk";
await capableAuthSDK.user.updateEmail(new_email);
// When updating a user's email address, a verification code is
// sent to the new address.
// The verification code must be passed to the following function to
// complete the update process.
await capableAuthSDK.user.verifyEmail(verfication_code);
Signed-in users: Update password
import capableAuthSDK from "@capable-health/capable-auth-sdk";
await capableAuthSDK.user.updatePassword(old_password, new_password);
Signed-in users: Update phone number
import capableAuthSDK from "@capable-health/capable-auth-sdk";
await capableAuthSDK.user.updatePhoneNumber(new_phone_number);
// When updating a user's phone number, a verification code is
// sent to the new number.
// The verification code must be passed to the following function to
// complete the update process.
await capableAuthSDK.user.verifyPhoneNumber(verfication_code);
Server-side authentication
Below, we show how to configure your app to use the Capable Health API from a backend service.
You can find the following OAuth2 configuration details on the API credentials page in your developer portal:
- OAuth2 token URL
- Client ID
- Client secret
Acceptable use
Server-side access, otherwise known as machine-to-machine (M2M) access, should only be performed from a trusted private resource, e.g., your backend server. It should never be performed from a client-side context where the provided credentials can be compromised. The client secret should be kept private, should never be committed to a source control system (e.g., git), and should never be sent to or used within a mobile or web application.
Please note: The code snippet below can be used by a Node.js backend. If you’re using another programming language, you’ll need to access our server-side authentication endpoints directly using our API. Please contact us for more information if you’re not using Node.js and want to access the Capable Health API from a backend server.
import capableAuthSDK from "@capable-health/capable-auth-sdk";
const access_token = await capableAuthSDK.machineToMachine.getAccessToken(
url,
client_id,
client_secret,
);
const response = await axios({
method: 'GET',
baseURL: 'https://api.sandbox.capablehealth.com',
url: '/patients',
headers: {
Authorization: `Bearer ${access_token}`,
},
});
Server-side impersonation
If you are re-platforming to Capable Health and your application has an authentication system that you want to retain, you can use server-side impersonation tokens to authenticate your users as Patients within Capable.
Server-side impersonation: Signup
To use impersonation in Capable, you first must create a Patient record for each user whom you want to grant access to Capable resources. We recommend using the POST /patients endpoint for this purpose. Please note: Patients created with the POST /patients endpoint will not be able to authenticate directly with Capable — they will only have access to Capable resources via the server-side impersonation tokens.
Server-side impersonation: Sign-in
After a Patient record has been created for a user in Capable, you can use the capableAuthSDK.impersonation.signIn method to sign them in:
import capableAuthSDK from "@capable-health/capable-auth-sdk";
const access_token = await capableAuthSDK.impersonation.signIn(
email,
url,
client_id,
client_secret,
);
Once the user is impersonated, all actions referenced in the signed-in user section are possible.
Background information
Access to most of the Capable Health API is granted by supplying a JSON Web Token (JWT) in the Authorization header. Tokens have limited access based on parameters supplied when creating them and have a limited lifespan before they expire. Once expired, you should request a new one.
The API provides two different authentication flows:
- Mobile app & SPA access via the Secure Remote Password Protocol
- Machine-to-machine access via the client credentials flow
Both authentication-flow types provide a JWT, which is then used to access the Capable Health API.
Updated 4 months ago