Site approval

Markdown

Your user approves each site before your app can use it. Apigami shows your app’s name and the site you’re asking for. The user can allow access, decline it or remove it later.

Some sites may already be approved when your app first calls. When the user attached their browser in Apigami’s window during the connection, the same click approved the domains your manifest declares with "via": "extension", and those of the applications it uses. Every other site goes through the approval below.

So a person who has just connected may still see the approval window at your app’s first call on a site: when their browser was already attached to their account, the connection showed no Apigami window and approved nothing, and a site your manifest declared after they connected was never shown to them. Tell them to expect it, and to click Authorize in it.

From Apigami 0.15.0, the approval window also shows the email of the account it decides for. When several accounts attached to that browser are connected to your app, the user picks one in the window, and the decision holds for that account only.

An approval belongs to the user, not to one browser: it applies in every browser attached to their account. Each browser also holds the browser’s own permission for the site, and Apigami only sends a call to a browser that has it.

Asking

Make your first POST /call for a site. Apigami opens the approval window and waits up to 45 seconds for the user’s answer.

What the user does	What your app receives
Allows access	The request completes and returns its result.
Declines	`403 no grant`. Respect the decision; don’t retry automatically.
Hasn’t answered yet	`403 consent requested` with `consentPending: true`. Try again after they answer.

Later calls use the saved decision. Repeating a pending request doesn’t open another window.

What a domain covers

Use a hostname such as example.com, without a URL path. Approval also covers its subdomains, such as api.example.com, over HTTPS. It doesn’t allow access to other sites.

Refusals and revocation

A declined site isn’t requested again. The user can change the decision from Apigami’s menu in any of their browsers. A refusal or a revocation applies to all of them at once, and stops subsequent calls with 403 no grant. Live streams on that site close with revoked.

Listen for app_user.updated events to keep your app up to date with these decisions.

Ask during onboarding

If you’d like to ask for a site before making a call, use POST /requests:

curl https://api.eu.apigami.com/requests \
  -H "Authorization: Bearer $APIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"user_ref\": \"$APIGAMI_USER_REF\",
    \"targetDomain\": \"example.com\"
  }"

Keep the user’s browser online for this step. The window opens in the browser Apigami would use for a call to that site; add install_ref to choose it.

Approval request responses

Response	Meaning
`200 { "ok": true }`	The approval window has been requested. The user’s answer is still pending.
`200 { "ok": true, "granted": true }`	The user already approved this site.
`403 no grant`	The user previously declined or revoked this site.
`503 extension offline`	The browser is offline. Ask again when it’s connected.
`503 extension outdated`	Apigami in that browser must be updated. Chrome installs the update on its own; ask again once it has reconnected.

The user must already be connected to your app, or the API returns 403 not paired without opening a window.