The operator's permission

Each operator gives your software access from Qbox. It is OAuth 2.0 with authorization code and PKCE (RFC 6749 and RFC 7636).

The flow

1. The connection starts in your software or in Qbox. From Qbox, in “Connect your software”, the operator picks yours and we take them to your connectUrl, the one you set in your area. There they sign in to your software, which knows who they are.
2. Your software sends them to ask for access at https://app.findqbox.com/oauth/authorize, with response_type=code, client_id, redirect_uri (one of those in your area), scope, state and code_challenge with code_challenge_method=S256.
3. The operator gives access in Qbox. They see what your software will be able to do and what not, choose where their requests go and accept Qbox's terms for centres.
4. We return to your redirect_uri with code and state. The code is valid for 5 minutes and only once.
5. Your server exchanges it for tokens, with your credentials.

curl -X POST https://api.findqbox.com/connect/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=https://your-software.example.com/qbox/callback \
  -d code_verifier=$CODE_VERIFIER

Scopes

• facilities.write: publish the operator's centres and keep them up to date.
• leads.read: receive their requests.

Renewing the token

The access_token lasts an hour. To renew it, grant_type=refresh_token with the refresh_token. Each time you get a new one and the previous one stops working; one unused for 90 days expires. If someone uses one that was already exchanged, we revoke every token of that permission for safety, and the operator has to give it again.

Your software's token

With your credentials alone (grant_type=client_credentials) you get your software's token. It sees no centre: it's for listing your connections (GET /connections) and sending yourself a test webhook (POST /webhooks/test).

If the operator withdraws access

They can do it in Qbox at any time. You get the connection.revoked webhook, their tokens answer 403 connection_revoked and their centres stop being updated: they stay on the portal like the ones added in Qbox, with “Request information”.

In production, return URLs are always https://. In testing, http://localhost works too.