Pairing

Developer Mode clients must be paired before they can read scoped data. Pairing is per client. Revoking one client does not revoke other clients.

Flow

1. Enable Developer Mode in SuperAge Settings.
2. Accept the Developer Mode terms.
3. Keep the Developer Mode settings page open. New clients are discoverable and pairable only while this page is open.
4. Verify the certificate fingerprint shown by the app before sending the pairing request.
5. Start pairing from the local client.
6. Review the pending client request in the app.
7. Approve or deny the request.
8. Store the issued client token locally on the paired device.

Create a Request

curl --request POST \
  --url "<LAN_API_URL>/api/v1/pairing/requests" \
  --header "Content-Type: application/json" \
  --data '{
    "displayName": "Home Mac",
    "scopes": ["superage.metrics", "superage.workouts"]
  }'

The response contains a requestId and a temporary pollingToken. This token can only poll the pairing request. It cannot read SuperAge data.

SuperAge keeps the pairing window intentionally narrow. Pending requests expire, and repeated requests from the same remote address may receive 429 rate_limited until stale requests are cleared or expire.

Approve in SuperAge

The pending request appears inside the Developer Mode settings page. Approving the request creates a paired client with the requested scopes. Denying it leaves the local client without a data API token.

Poll for the Token

curl --request GET \
  --url "<LAN_API_URL>/api/v1/pairing/requests/<REQUEST_ID>" \
  --header "Authorization: Bearer <POLLING_TOKEN>"

Pending responses include "status": "pending" and no bearerToken. After approval, the response includes "status": "approved" and a bearerToken. Use that token for scoped data endpoints:

curl --request GET \
  --url "<LAN_API_URL>/api/v1/metrics" \
  --header "Authorization: Bearer <CLIENT_TOKEN>"

Fingerprint

The local API uses HTTPS with an app-generated certificate. Before creating a pairing request, the client should compare its observed certificate fingerprint with the fingerprint shown inside SuperAge.

Expected fingerprint: <CERTIFICATE_FINGERPRINT>

Do not create or continue pairing if the fingerprints do not match.

Revocation

Open Developer Mode settings in SuperAge and revoke the client. Revocation stops that client from reading future API responses. Other paired clients continue to work if they remain authorized.