Skip to content

Build an app

Install with OAuth

On this page

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#

  1. Someone presses Install on your listing. Bizisy sends the browser to your install_url with ?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.)

  2. Your app redirects the browser to https://<company>.bizisy.com/api/oauth/authorize with:

    ParameterValue
    response_typecode
    client_idYour app's id (bza_…)
    redirect_uriOne of the manifest's redirect_uris, exactly
    stateAn unguessable value you check on return
    code_challenge, code_challenge_methodPKCE, S256 only
    scopeOptional: space-separated scopes, a subset of your manifest's; all of them when left out
  3. 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.

  4. The browser comes back to your redirect_uri with code, state and iss. Check state, and check that iss is the company you started with. If they declined, you get error=access_denied.

  5. Your server exchanges the code at https://<company>.bizisy.com/api/oauth/token:

Shell
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
JSON
{
  "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).

  1. Call platform_app_installs_me to 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#

TokenLifetimeNotes
Authorization code2 minutesSingle use; the consent page waits 10 minutes
Access token1 hourSend as Authorization: Bearer bzat_…
Refresh token180 daysRotates on every use: keep the newest
Shell
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.

Shell
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.

Developer docs