Hosted auth
Your users link their own accounts, on a page you brand, without a credential reaching you.
aux0 serves the page where your user links their account. You never hold a password, a QR scan or a one-time code — which is also the shortest answer to most of a security review.
Create a link
curl https://api.aux0.com/v1/hosted_auth \
-H "Authorization: Bearer $AUX0_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"end_user_id": "u_maya",
"providers": ["gmail", "outlook", "icloud"],
"success_url": "https://app.example.com/settings/channels",
"expires_in": 86400
}'| Field | |
|---|---|
end_user_id | Your own id for this person. Required. |
providers | Which to offer. Omit for every provider you have enabled. |
success_url | Where to return the user. They arrive with ?account_id=. |
expires_in | Seconds, up to 7 days. Defaults to 24 hours. |
Links are single-use. Create one per attempt rather than storing one.
What the user sees
Your logo, your colours, your copy. The only aux0 on the page is one line in the footer, which the providers require.
Each provider asks for what it needs — Gmail and Outlook hand the user to their own consent screen, iCloud and IMAP ask for a server address and an app password. If a provider then asks the user to confirm their identity, that step appears on the same page rather than failing.
What you get back
{
"type": "account.connected",
"data": {
"account": {
"id": "acc_8kd2nR4p",
"provider": "gmail",
"end_user_id": "u_maya",
"status": "syncing"
}
}
}Then account.sync_completed when the backfill finishes. The account is
usable from the first event; the second only means the history is complete.
Reconnecting a broken account
The same endpoint. When an account needs attention, create a link for the same
end_user_id, and the page opens on the step that provider needs. The
account.needs_attention event already includes a reconnect_url, so the
usual implementation is to show that.
Branding
Set the logo, the accent colour and the product name per project in Settings. On a paid plan the page can also be served from your own subdomain, so the user never leaves a domain they recognise.
Why not build your own form
You can. Posting credentials to /v1/accounts is a documented endpoint. But
then:
- The password is in your request logs, your error tracker and your memory dumps.
- Your security review now covers credential handling for every provider.
- A two-factor prompt, an expired app password and a revoked grant are each a flow you have to build and keep working as the provider changes it.
Hosted auth exists so none of that is yours. Use it unless you have a specific reason not to.