Register a new user
Create a new account via AWS Cognito. The account is confirmed immediately and a verification link is mailed to the address; the email stays unverified until that link is followed (see GET /cognito/verify-email), and several write endpoints refuse an unverified account. Gated by the features.user_registration flag — when the flag is off the endpoint answers 403. Rate limited to 10 requests per minute per IP. When the risk engine flags the caller (repeated sign-ups from one IP), a reCAPTCHA token must be sent as captchaToken.
Request Body
Responses
Account created; verification email sent.
Confirm registration
Confirm a Cognito account with a verification code. Sign-up already confirms the account itself, so this is needed only when POST /cognito/signup answered userConfirmed: false. It does not mark the email verified — that is the link sent by sign-up.
Request Body
Responses
Account confirmed
Sign in
Authenticate with email and password. Tokens are not returned in the body: the session is set as httpOnly cookies (access_token, id_token, refresh_token) that the browser sends on every later request. Scripts and server-to-server integrations should use an API key instead (see Authentication). When the risk engine flags repeated failures, a reCAPTCHA token must be sent as captchaToken. If Cognito asks for a further challenge, the body carries challengeRequired: true, challengeName and session and no cookies are set.
Request Body
Responses
Authentication successful; session cookies set.
Refresh tokens
Exchange the refresh_token cookie for new access and ID token cookies. There is no request body — a refresh token sent in JSON is ignored.
Responses
Tokens refreshed; new access_token and id_token cookies set.
Sign out
Get current user
The signed-in user's profile. Cookie session only — this endpoint does not accept an Authorization header or an API key. When the short-lived session has expired but the refresh cookie is still valid, it renews the session transparently and sets new cookies. While FundlyHub support is viewing the account on the user's behalf it returns that user with is_impersonating: true and impersonated_by.
Responses
Current user info
Request password reset
Send a password reset code to the user's email. Answers 200 whether or not the address has an account, so it cannot be used to discover accounts.
Request Body
Responses
Reset code sent, if the account exists
Reset password
Initiate OAuth login
Redirect to the Cognito Hosted UI for a third-party provider. After the provider signs the user in, GET /cognito/oauth/callback sets the session cookies and redirects to redirect on the FundlyHub site.
Open this URL in the browser that will be signed in, by navigating to it rather than fetching it. The response sets a short-lived httpOnly cookie that the callback requires. A sign-in completed in a different browser, after about ten minutes, or after a newer sign-in was started in the same browser is refused, and the browser is sent to /auth?error=state_mismatch with no session set; starting again fixes it.
Parameters
Path Parameters
"google""apple"Query Parameters
The path on the FundlyHub site to send the browser to after sign-in, such as /campaigns/help-food-bank?tab=updates. It must start with a single /; a full URL on the FundlyHub site is reduced to its path. Any other value, such as a URL on another host or a protocol-relative //host, is replaced by /. Defaults to /.
"/campaigns/help-food-bank"2048Responses
Redirect to the OAuth provider. Sets the short-lived sign-in cookie that the callback checks.
Change password
Changes the password of an email/password account, given the current one.
Cookie session only. A request authenticated with an Authorization: Bearer header or an API key answers 401 Not authenticated. Google and Apple accounts have no password to change.
Rate limited at 10 requests/minute per IP (authentication bucket).
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Request Body
Responses
Password changed
Resend the email-verification link
Sends a fresh verification link to the account registered under email (matched case-insensitively against the login address, not the private contact address — for that use POST /users/me/private-contact/resend).
Always answers 200 with the same message, whether or not the address has an account and even when sending fails, so it cannot be used to discover accounts.
No authentication. Rate limited at 5 requests/minute, keyed by user when a session is present and by IP otherwise.
Request Body
Responses
Accepted (sent if the address is known)
Verify an email address (link target)
The URL in verification emails. Consumes the token and always redirects to the frontend with the outcome in a query parameter; it never returns JSON.
?verification= is one of: success; invalid (no token); failed (unknown, used or expired token); contact_taken (the link proved a private contact address another account already holds); error (unexpected failure).
When the link proved the account's login address, the Cognito email_verified attribute is updated too, and any pending ambassador invitation for that address is settled.
No authentication. Rate limited at 300 requests/minute per IP.
Parameters
Query Parameters
Responses
Redirect to {FRONTEND_URL}/?verification=<outcome>
OAuth callback (Google / Apple)
The Cognito Hosted UI's redirect_uri after a Google or Apple sign-in, started at GET /cognito/oauth/{provider}. Not called by API clients directly.
Exchanges code for tokens, provisions or links the profile, sets the access_token, id_token and refresh_token httpOnly cookies, and redirects to the URL carried in state — which is the redirect query parameter given when the flow was started, or the frontend root.
Every failure is also a redirect, to {FRONTEND_URL}/auth?error=…: unverified_account_exists (a provider identity linked to a native account whose address was never verified), missing_code, token_exchange_failed, invalid_token, oauth_error, or the provider's own error with a message.
Parameters
Query Parameters
Authorization code from Cognito.
Where to send the browser after a successful sign-in.
Responses
Redirect — to state on success (with session cookies set), or to /auth?error=… on the frontend.