Tokens

All token calls go from your server to https://api.splashifypro.com/api/v1/oauth/token. Never call it from a browser or a mobile app: it needs your client secret.

Token	Starts with	Lasts
Authorization code	`spo_ac_`	60 seconds, one use
Access token	`spo_at_`	1 hour
Refresh token	`spo_rt_`	90 days without use; a new one with every refresh, for as long as the account keeps your app connected

Tokens are random strings, not JWTs. Do not try to read anything from them.

Client authentication

Send your Client ID and secret in one of two ways:

HTTP Basic (preferred): Authorization: Basic base64(client_id:client_secret). curl -u "spo_app_...:spo_cs_..." does this for you.
In the body: client_id and client_secret fields.

A secret in the query string is refused. Bodies can be application/x-www-form-urlencoded or application/json.

Swap the code

curl -X POST https://api.splashifypro.com/api/v1/oauth/token \
  -u "spo_app_XXXX:spo_cs_YYYY" \
  -d grant_type=authorization_code \
  -d code=spo_ac_ZZZZ \
  -d redirect_uri=https://yourapp.example/splashify/callback \
  -d code_verifier=VERIFIER

Field	Value
`grant_type`	`authorization_code`
`code`	The `code` from the redirect
`redirect_uri`	The same `redirect_uri` you sent to the authorize page
`code_verifier`	The PKCE verifier you kept for this sign-in

{
  "access_token": "spo_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "spo_rt_...",
  "scope": "account:read whatsapp.messages:send whatsapp.templates:read",
  "account_id": "6f1c2a8e-...",
  "platform": "whatsapp"
}

Save the refresh token (encrypted) against account_id. scope is what the token can do right now: permissions that need a verified app are left out while your app is not verified.

A code works once. If the same code is used again by your app, we sign out the tokens it gave, because someone may have copied it.

Refresh

curl -X POST https://api.splashifypro.com/api/v1/oauth/token \
  -u "spo_app_XXXX:spo_cs_YYYY" -d grant_type=refresh_token -d refresh_token=spo_rt_BBBB

The answer has the same shape, with a new refresh token. Rules:

Save the new refresh token every time, before you use the new access token. The old one stops working the moment it is used.
A spent refresh token used again within 10 seconds (for example a retry after a lost answer) gets invalid_grant and changes nothing. Ask the user to connect again if you lost the new one.
A spent refresh token used again after 10 seconds looks like a stolen token: we sign out that connection's tokens, email you a security alert and answer invalid_grant. The user has to connect again.
At most 60 refreshes an hour per connection.

Narrow the permissions

Add scope to a refresh to get tokens with fewer permissions, for example a token that can only read templates:

-d grant_type=refresh_token -d refresh_token=spo_rt_BBBB -d "scope=whatsapp.templates:read"

The list must be part of what the account allowed. account:read is always kept. A refresh can never add permissions: for more, send the user to the authorize page again.

Revoke

curl -X POST https://api.splashifypro.com/api/v1/oauth/revoke \
  -u "spo_app_XXXX:spo_cs_YYYY" -d token=spo_rt_BBBB -d revoke_grant=true

Field	Value
`token`	An access token or a refresh token of your app
`token_type_hint`	Optional: `access_token` or `refresh_token`
`revoke_grant`	Optional. `true` also disconnects the account from your app, as if the user removed it.

The answer is always 200 {} once your client is authenticated, even for a token that is unknown or already revoked. Revoking a refresh token signs out the tokens it came with.

Who is connected

curl https://api.splashifypro.com/api/v1/oauth/me -H "Authorization: Bearer spo_at_AAAA"

{
  "account_id": "6f1c2a8e-...",
  "platform": "whatsapp",
  "name": "Asha Traders",
  "scopes": ["account:read", "whatsapp.messages:send"],
  "client_id": "spo_app_XXXX"
}

Token errors

HTTP	`error`	When
400	`invalid_request`	A field is missing, or the secret was sent in the query string.
401	`invalid_client`	Wrong Client ID or secret, or the app was deleted. Comes with `WWW-Authenticate: Basic`.
400	`unauthorized_client`	The app or your developer account is suspended.
400	`invalid_grant`	The code or refresh token is wrong, expired, already used, for another app, or the account removed your app. Send the user to connect again.
400	`unsupported_grant_type`	`grant_type` is not `authorization_code` or `refresh_token`.
400	`invalid_scope`	A refresh `scope` that is not part of what the account allowed.
429	`rate_limited`	Too many calls; wait for `Retry-After` seconds.

After 10 failed client authentications in 10 minutes from one IP address, that address is blocked for your Client ID for 15 minutes. Other addresses are not affected.

The Email platform

Everything on this page is the same for Email apps. Only the authorize host differs (email.splashifypro.com), and platform is email.