Skip to main content
Borough supports two authentication methods: API keys (simplest) and OAuth 2.1 (for MCP clients and third-party integrations).

​
API Key (Bearer Token)

Include your API key in the Authorization header: 
Authorization: Bearer BOROUGH-<your-license-key>
Keys use the format BOROUGH-<uuid> and are provisioned automatically when you subscribe to a plan. 
BOROUGH-a1b2c3d4-e5f6-7890-abcd-ef1234567890
Keys are validated against Polar.sh and cached for 10 minutes. If your key is revoked, cached access stops within 10 minutes.

​
OAuth 2.1 (PKCE)

Borough implements OAuth 2.1 with PKCE for secure delegated access. This is the recommended method for MCP clients and third-party apps.

​
Endpoints

EndpointMethodDescription
/oauth/registerPOSTDynamic client registration (RFC 7591)
/oauth/authorizeGETConsent page (redirects user)
/oauth/authorizePOSTSubmit API key, receive auth code
/oauth/tokenPOSTExchange code for tokens
/.well-known/oauth-authorization-serverGETServer metadata (RFC 8414)
/.well-known/oauth-protected-resourceGETResource metadata (RFC 9728)

​
Flow

  1. Register your client (optional for localhost apps): 
    curl -X POST https://borough.qwady.app/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name":"My App","redirect_uris":["https://myapp.com/callback"]}'
    Unregistered clients may only use localhost redirect URIs.
  2. Redirect user to authorize: 
    GET /oauth/authorize?response_type=code
  &client_id=<client_id>
  &redirect_uri=<redirect_uri>
  &code_challenge=<S256_challenge>
  &code_challenge_method=S256
  &state=<random_state>
    The user enters their Borough API key (or continues with Free tier) and is redirected back with an authorization code.
  3. Exchange code for tokens: 
    curl -X POST https://borough.qwady.app/oauth/token \
  -d "grant_type=authorization_code&code=<code>&client_id=<client_id>&code_verifier=<verifier>&redirect_uri=<redirect_uri>"
  4. Use the access token: 
    Authorization: Bearer <access_token>

​
Token lifetimes

TokenLifetime
Access token1 hour
Refresh token30 days
Auth code5 minutes
Client registration30 days
Use the refresh token to get new access tokens without re-authorization: 
curl -X POST https://borough.qwady.app/oauth/token \
  -d "grant_type=refresh_token&refresh_token=<token>&client_id=<client_id>"
The refresh flow re-validates your API key, so tier changes and revocations take effect on the next refresh.

​
Free-tier access

Search endpoints (/v1/search/rentals, /v1/search/sales), areas (/v1/areas), and market endpoints work without authentication. Unauthenticated requests are subject to:
  • 10 requests/minute rate limit (IP-based)
  • 100 requests/month quota
  • Maximum 10 results per page

​
Error responses

CodeStatusDescription
MISSING_API_KEY401No Authorization header provided on a protected endpoint
INVALID_API_KEY401Key doesn’t match any active subscription
EXPIRED_API_KEY401Subscription has ended
TIER_RESTRICTED403Endpoint requires a higher tier
On 401 responses, the WWW-Authenticate header includes a link to the protected-resource metadata for automatic OAuth discovery.

​
Security best practices

  • Store keys in environment variables, never in client-side code
  • Rotate keys by creating a new subscription if compromised
  • Use the minimum tier needed for your use case
  • For OAuth, always use PKCE with S256 code challenges
  • Register your client to restrict allowed redirect URIs