Authorization

To connect an account, send the user's browser to our authorize page. After the user decides, we send the browser back to your redirect URL with a code, or with an error.

Authorize URLs

App platform	URL
WhatsApp	`https://app.splashifypro.com/oauth/authorize`
Email	`https://email.splashifypro.com/oauth/authorize`

An app opened on the wrong host shows a page with a button to the right one.

Parameters

Parameter	Required	Value
`response_type`	yes	`code`
`client_id`	yes	Your Client ID, `spo_app_...`
`redirect_uri`	yes	One of your registered redirect URLs, exactly as registered
`scope`	yes	Permissions, separated by spaces, for example `whatsapp.messages:send whatsapp.templates:read`. Up to 20, 400 characters in all, lower case as listed in Permissions. Only permissions your app declared. `account:read` is always added.
`state`	yes	A random value you make for this sign-in and check when the user comes back. 8 to 512 printable characters, no spaces.
`code_challenge`	yes	`BASE64URL(SHA256(code_verifier))`, 43 to 128 characters
`code_challenge_method`	yes	`S256` (plain is not accepted)

prompt and login_hint are ignored.

PKCE

For each sign-in, make a code_verifier of 43 to 128 characters from A-Z a-z 0-9 - . _ ~ (32 random bytes in base64url works), keep it on your server with the state, and send its SHA-256 in base64url as code_challenge. You send the verifier itself when you swap the code for tokens.

const verifier = crypto.randomBytes(32).toString("base64url");
const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");

The user signs in to Splashify Pro if needed, then sees:

your app's logo and name;
for a verified app: "by" the legal name we confirmed and a green Verified badge;
for any other app: "by an unverified developer", your email domain when it is a company domain, and a notice that we have not checked the app;
the account being connected;
what your app will be able to do, in plain words, with permissions they already allowed in a separate list;
that messages are charged to their wallet or account, and the daily limit while your app is not verified;
a notice when their account only accepts API calls from allowed IP addresses, with the server IPs you listed on your app;
where they go back to, and your privacy and terms links;
Cancel and Allow.

The consent screen for Demo CRM, by an unverified developer (example.com), with the amber not checked notice, Priya Sharma's account box, the permissions, the charge note with 500 messages a day, the return line and Cancel and Allow — An unverified app on the consent screen.

The consent screen for Demo CRM, by Demo CRM Private Limited with the green Verified badge, and one new permission above an Already allowed (2) list — A verified app, asking for one more permission.

Only the account owner can allow. The screen shows a notice instead of Allow when:

Why	What the user sees
A team member is signed in	Only the account owner can connect apps.
Splashify Pro support is signed in to the account	Apps cannot be connected in this mode.
The account belongs to a reseller	Connected apps are not available on this account.
The plan has no API access (WhatsApp)	A link to upgrade the plan.
No WhatsApp number is connected and you ask to send messages	A link to connect WhatsApp.
You ask for a permission that needs a verified app	Ask the developer to get the app verified.
Your unverified app has 25 connected accounts	Ask the developer to get the app verified.

The user can still click Cancel.

When an account allows your app a second time, the new permissions are added to what it allowed before. Tokens always carry everything the account allowed.

Coming back to your app

After Allow, the screen shows Connected and then takes the user back to your redirect URL by itself, with a Continue link in case that does not happen; after Cancel, the user goes back at once.

After Allow, the user sees Connected and goes back to your app.

Allowed:

https://yourapp.example/splashify/callback?code=spo_ac_...&state=YOUR_STATE&iss=https%3A%2F%2Fapi.splashifypro.com

Check that state is the one you made for this sign-in and that iss is https://api.splashifypro.com. Then swap the code within 60 seconds. See Tokens.

Cancel or an error:

https://yourapp.example/splashify/callback?error=access_denied&error_description=The+user+said+no&state=YOUR_STATE&iss=https%3A%2F%2Fapi.splashifypro.com

state is left out when the one you sent was not valid.

Errors

Errors shown on our page

These never go back to your app, because we cannot trust the redirect URL yet. The user sees the message.

Error	When
`invalid_client`	The Client ID is wrong or the app was deleted.
`app_unavailable`	The app or its developer account is suspended.
`invalid_redirect_uri`	`redirect_uri` does not match a registered URL exactly.
`wrong_platform`	A WhatsApp app opened on the Email host, or the other way round. The page links to the right host.

Errors sent back to your redirect URL

Checked in this order, after the four above:

`error`	When
`unsupported_response_type`	`response_type` is not `code`.
`invalid_request`	`state` is missing or not valid, or PKCE is missing or not S256 (`error_description`: "PKCE with S256 is required").
`invalid_scope`	An unknown permission, one for the other platform, or one your app did not declare.
`access_denied`	The user clicked Cancel.

For a verified app and a signed-in user, we send these back at once. For any other app (or a user who is not signed in), we first show a page that says "This link has a problem, so the app asked to send you back to <your host>" with a Continue button. This stops anyone from using our pages to send people to a site of their choosing.