Skip to main content

Connect an app with FairClose OAuth

Connect Crossflo or another registered app without sharing your FairClose password. Each seller signs in on FairClose, completes existing security checks and approves the requested permissions.

For sellers

Start from the connecting app. Check its name and permissions on the FairClose approval page. Cancel if anything looks wrong. Review and revoke connections in Apps & API. Keep two-factor authentication enabled.

An app must implement this OAuth flow before its Connect button can use it. Existing API-key connections remain available with their existing permissions.

For app developers

  1. Ask a FairClose administrator to register your app under API Management → OAuth apps. Supply verified HTTPS app, support and exact callback URLs. Apps start disabled.
  2. Generate a new random state and a 43–128 character PKCE verifier per connection. Store these server-side, bound to the user’s app session. Use S256 for the challenge.
  3. Redirect to https://fairclose.co/oauth/authorize with response_type=code, client_id, redirect_uri, scope, state, code_challenge and code_challenge_method=S256.
  4. On the callback, verify state against the initiating session before using the code. Handle access_denied without replacing an existing connection.
  5. POST a URL-encoded authorization_code grant to /api/v1/oauth/token with code, client_id, the same redirect_uri and code_verifier. Server apps authenticate using HTTP Basic or client_secret_post. Public/native apps use PKCE without a secret.
  6. Store tokens securely per seller connection. Call only the OAuth listing endpoints using Authorization: Bearer. Serialize refresh requests per connection and atomically replace each refresh token; reusing an old refresh token revokes the connection.

Scopes and listing endpoints

PermissionEndpoint under /api/v1/oauth
profile.readGET /me
listings.readGET /listings and GET /listings/{id}
listings.writePOST /listings (draft) and PUT /listings/{id}
listings.publishPOST /listings/{id}/publish
listings.endPOST /listings/{id}/end
offline_accessRotating refresh tokens for background access

Listing bodies use the existing seller listing schemas. Creation saves a draft; status changes use the publish/end endpoints. Changes to scheduling, duration or automatic relisting require both listings.publish and listings.end in addition to listings.write. Reads accept status, limit (up to 200) and skip for paginated exports. Existing plan limits, listing fees, edit restrictions, auction scheduling, bids and order protections apply.

Token lifecycle

Access tokens last up to 10 minutes. Offline connections last up to 30 days and require refresh_token grants at the token endpoint. Request offline_access only when background access is needed. POST token revocation to /api/v1/oauth/revoke with the app’s client authentication. Endpoint metadata is available at /api/v1/oauth/metadata.

Revocation, app disablement or configuration changes, password resets and revoked originating sessions invalidate access. There are no OAuth scopes for payments, payouts, orders, charity disbursements, account security or admin actions.

Help Center