Build an app
Install with OAuth
Your app is an OAuth 2.1 confidential client of Bizisy. A company's owner or admin installs it with the authorization code flow and PKCE; your server exchanges the code for tokens that act as that company's install of your app.
The flow#
Someone presses Install on your listing. Bizisy sends the browser to your
install_urlwith?iss=https://<company>.bizisy.com: the company's address, which is its authorization server. (You can also start at step 2 if you already know the company.)Your app redirects the browser to
https://<company>.bizisy.com/api/oauth/authorizewith:Parameter Value response_typecodeclient_idYour app's id ( bza_…)redirect_uriOne of the manifest's redirect_uris, exactlystateAn unguessable value you check on return code_challenge,code_challenge_methodPKCE, S256onlyscopeOptional: space-separated scopes, a subset of your manifest's; all of them when left out The person signs in to their company and sees the consent page: your app, its developer, whether Bizisy reviewed it, and each scope in plain words. An owner or admin presses Install (with a sign-in from the last 12 hours); anyone else is told to ask one.
The browser comes back to your
redirect_uriwithcode,stateandiss. Checkstate, and check thatissis the company you started with. If they declined, you geterror=access_denied.Your server exchanges the code at
https://<company>.bizisy.com/api/oauth/token:
curl https://acme.bizisy.com/api/oauth/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=authorization_code \
-d code="$CODE" \
-d code_verifier="$VERIFIER" \
-d redirect_uri=https://payroll.example.com/oauth/bizisy/callback{
"access_token": "bzat_…",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "bzrt_…",
"scope": "people:view",
"install_id": "01k…"
}redirect_uri is required and must be the one of the authorization request. Client authentication is client_secret_basic (as above) or client_secret_post (client_id and client_secret in the body).
- Call
platform_app_installs_meto learn the company (id, name, address), the scopes granted and your webhook endpoint, then issue your webhook signing secret.
Errors before Bizisy knows the redirect URI is yours (an unknown app, a redirect URI not in the manifest, a scope you didn't declare, a missing PKCE challenge) are shown on Bizisy's own page and never sent to any address.
Tokens#
| Token | Lifetime | Notes |
|---|---|---|
| Authorization code | 2 minutes | Single use; the consent page waits 10 minutes |
| Access token | 1 hour | Send as Authorization: Bearer bzat_… |
| Refresh token | 180 days | Rotates on every use: keep the newest |
curl https://acme.bizisy.com/api/oauth/token -u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=refresh_token -d refresh_token="$REFRESH_TOKEN"A refresh token used twice revokes the install's tokens for safety (two refreshes racing within 10 seconds are refused, not punished); the company then installs your app again. Revoke tokens yourself at /api/oauth/revoke (RFC 7009). Store tokens and your client secret on your server only.
Calling Bizisy#
Use the access token on the developer API, https://api.bizisy.com/v1/…, on https://api.bizisy.com/mcp/manage, or on the company's own address. A token never works for another company. Each install may make 300 requests a minute.
curl -X POST https://api.bizisy.com/v1/org/people.list -H "Authorization: Bearer $ACCESS_TOKEN" -H 'content-type: application/json' -d '{}'Tokens stop working when the company uninstalls your app, when Bizisy suspends it, when you delete it, or when the company's account is paused or closed.
Rotating your client secret#
the developer console → your app → Credentials → Create a new secret replaces it at once: token requests with the old one fail from then on. Deploy the new one first if you can't afford a gap.
Something missing or wrong on this page? Write to hello@bizisy.com.