Hosted auth wizard

Learn how to use the hosted auth wizard to connect user accounts inside your application. Available for LinkedIn, WhatsApp, Instagram, Telegram, Google, Microsoft, and IMAP.

The hosted auth wizard is a pre-built, optimized authentication interface that simplifies the process of connecting user accounts securely. It reduces your development time and ships a streamlined connect experience out of the box. The wizard supports QR code scanning, credentials-based authentication, and OAuth, and you can show only the providers you allow your users to connect to.

Overview

You generate a single-use link from your backend, redirect the user to it, and postpress walks them through every provider-specific step. When the user finishes the flow we notify your backend with the new account id and any identifier you sent along.

Pass a name parameter with your internal user id when you request a hosted auth link. postpress returns it back on your notify_url so you can match the connected account to your user record.

Quickstart

To generate a hosted auth link, make an API request with these parameters:

  • type - create for a new connection or reconnect for a disconnected account.
  • api_url - your postpress API endpoint.
  • expiresOn - the expiration date and time of the link in ISO 8601. Keep this short, from a few minutes to a few hours. Links also expire on the daily restart. Generate a fresh link every time a user clicks the connect button in your app.
  • providers - the providers the user can choose from in the wizard. Pass a specific provider, an array of providers, or "*" for all of them.
  • success_redirect_url and failure_redirect_url - where to send the user after the flow finishes.
  • notify_url - a backend URL to receive a webhook with the new account details.
  • name - your internal user id. postpress returns it on the notify webhook so you can match the account to your user.
curl --request POST \
     --url https://api.postpress.ai/v1/hosted/accounts/link \
     --header 'X-API-KEY: ${POSTPRESS_API_KEY}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "type": "create",
  "providers": ["LINKEDIN", "WHATSAPP", "GOOGLE"],
  "api_url": "https://api.postpress.ai/v1",
  "expiresOn": "2026-06-30T12:00:00.701Z"
}'
Never expose your X-API-KEY in the browser. Generate the hosted link from a backend endpoint and return only the resulting URL to your frontend.

A successful request returns a hosted auth URL. This is the link that guides your user through the authentication flow.

{
  "object": "HostedAuthURL",
  "url": "https://auth.postpress.ai/pqb%2Gz77l.o72WXNPdqWX45jxqP5xMMlQp02zho8GAXZq0HWsAGiQ%3D"
}

We strongly recommend an automatic redirect when the user clicks Connect account in your app. Do not embed the link in an iframe. Some providers, including LinkedIn captchas and Microsoft OAuth screens, do not load correctly inside an iframe.

Step 4: Receive a callback when the account is added

When your user finishes connecting an account, postpress can call a URL of your choice with the new account_id and your internal id so you can persist the mapping for future API calls.

Add notify_url with your backend URL and name with your internal user id to the request payload.

curl --request POST \
     --url https://api.postpress.ai/v1/hosted/accounts/link \
     --header 'X-API-KEY: ${POSTPRESS_API_KEY}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "type": "create",
  "providers": "*",
  "api_url": "https://api.postpress.ai/v1",
  "expiresOn": "2026-06-30T12:00:00.701Z",
  "notify_url": "https://yourapp.com/postpress/account-callback",
  "name": "user_1234"
}'

After the user connects their account, postpress posts this payload to your notify URL:

{
  "status": "CREATION_SUCCESS",
  "account_id": "e54m8LR22bA7G5qsAc8w",
  "name": "user_1234"
}

Reconnecting an account

Reconnection follows the same path as the initial connection, but with type set to reconnect and an extra reconnect_account field that contains the account id you want to repair.

Example flow

  1. Set up a webhook that listens for account status updates. The status you care about is CREDENTIALS, which means the account needs to reconnect.
  2. When the CREDENTIALS event arrives, email the user with a link that starts the reconnection flow. Be clear about what they are clicking and reassure them about security.
  3. The link points at your backend. Your backend generates a fresh hosted auth link via the postpress API with type: "reconnect" and the stored reconnect_account.
  4. Redirect the user to that link. They follow the standard wizard to reconnect the account securely.

Custom domain (white-label)

You can use your own subdomain, for example auth.yourapp.com, in place of the default postpress URL. This feature is available on postpress plans with an active subscription.

1. Configure your DNS

  1. Create a CNAME record in your domain's DNS:
    • Name: the subdomain you want, for example auth.
    • Type: CNAME.
    • Target: auth.postpress.ai. (the trailing dot is optional depending on your registrar).
  2. Verify DNS propagation before contacting us. Tools like whatsmydns.net or dig let you confirm the CNAME is publicly visible. The CNAME must resolve to auth.postpress.ai, otherwise SSL certificate generation will fail.
DNS propagation can take up to 24 hours depending on your registrar.

2. Validation by postpress

Once the CNAME is active and publicly visible:

  • Contact postpress support with the full URL, for example https://auth.yourapp.com.
  • We finalize the configuration on our side and generate the SSL certificate.

3. Rewrite the hosted auth link

After postpress support confirms your CNAME setup, you can substitute your subdomain for ours in the hosted auth URL returned by the create link API call before redirecting your end users.

Updated May 2026