Custom token validation

If your app uses its own sign-in (provider custom), StickyHealth cannot check your tokens itself. Instead, your server hosts a validation endpoint: we send it the token, and it tells us who the user is. This page is the contract that endpoint must follow.

Overview

• You build the endpoint and send us its URL. We register it for your organization.
• The app never sends the URL. In the SDK, the custom provider's config has no URL field: auth={{ token, provider: 'custom', config: {} }}.
• On every sign-in from your app, StickyHealth calls the endpoint with the member's token, plus an authorization request when the app sent one (see Authorization requests).

Endpoint requirements

• Protocol: HTTPS
• Method: POST, JSON body
• Timeout: respond within 10 seconds, or the sign-in fails

Request

Token validation

{{code.b0}}

Token validation with an authorization request

{{code.b1}}

The entries contain only external_uid values. StickyHealth sets the permissions and the one-hour expiry itself. Your endpoint decides only whether the signed-in user may access each listed member.

Response

Basic response

{{code.b2}}

Response to an authorization request

When the request contains authorization_request, your response must contain authorization_request too, listing the entries you approve:

{{code.b3}}

Response requirements

1. Return HTTP 200 with a JSON body for a valid token.
2. sub is required: the user's id in your system. It becomes the member's external_uid, which webhooks and authorization requests use to refer to them.
3. If the request contained authorization_request, always echo authorization_request back with only the entries you approve. Leave out any entry the user may not access. Return "entries": [] to approve none.
4. Other fields are allowed. email, name and picture, if present, fill in the member's profile.

Validating authorization requests

When the request contains an authorization request:

1. Check permissions: make sure the authenticated user may access each requested member.
2. Check the ids: make sure each external_uid is a real user in your system.
3. Log it: record every authorization request for audit.

Never trust the requested list on its own: it comes from the app. Only your endpoint can confirm that the user may access those members.

Errors

For an invalid token or a failed check, return an error status. Any status outside 2xx fails the sign-in. We suggest:

• 400: invalid request format
• 401: invalid or expired token
• 403: the user may not grant the requested access
• 500: internal error

{{code.b4}}

Examples

A valid token:

{{code.b5}}

A valid token with an approved authorization request:

{{code.b6}}

Implementation example (Python, Flask)

is_valid_token, extract_user_from_token and can_access_member stand in for your own logic.

{{code.b7}}

Security requirements

1. Serve the endpoint over HTTPS only.
2. Rate-limit it.
3. Validate the request body.
4. Approve only members the authenticated user is allowed to manage.
5. Log every authorization request for audit.