Square OAuth Setup

Square uses OAuth — users authorize access from inside the app, no API key entry needed. As an admin you configure the app credentials once in .env; each company connects their Square account through the UI.

1. Create a Square application

Go to developer.squareup.com and sign in with your Square account.

1. Click Create an Application
2. Give it a name (e.g. "Geekonomics")
3. Open the app and go to OAuth in the left sidebar

2. Configure the OAuth redirect URL

In your Square app's OAuth settings, add your redirect URL:

https://your-domain.com/api/square/oauth/callback

Replace your-domain.com with your actual domain. This must match exactly — Square rejects unregistered URLs.

Sandbox vs Production

Square has separate Sandbox and Production environments with different credentials. During testing, use sandbox credentials and SQUARE_ENVIRONMENT=sandbox. Switch to production credentials before going live.

3. Get your credentials

From your Square app's OAuth page:

• Application ID → SQUARE_APP_ID
• Application Secret → SQUARE_APP_SECRET

4. Add to .env

SQUARE_APP_ID=sq0idp-your-app-id
SQUARE_APP_SECRET=sq0csp-your-app-secret
SQUARE_ENVIRONMENT=production

Restart the container after editing .env:

docker compose restart

5. Connect from the app

Once the env vars are set, users can connect Square from Square Sync:

1. Click Connect Square
2. Authorize on Square's OAuth page
3. You'll be redirected back to Geekonomics
4. Click Sync Now to pull transactions

Token management

Square access tokens expire and are auto-refreshed by Geekonomics before each sync (when within 7 days of expiry). Tokens are stored AES-256-GCM encrypted in the database. They are never returned in API responses — only a status indicator is shown.

To disconnect Square: click Disconnect on the Square Sync page. This removes the stored tokens. The user can reconnect at any time by going through the OAuth flow again.