REST API Architecture#

Sure exposes a versioned REST API under /api/v1, implemented as a dedicated Rails namespace entirely separate from the web layer. The API has 33 controllers covering resources from accounts and transactions to AI chats and OAuth metadata 12.

Controller Hierarchy#

All API controllers inherit from Api::V1::BaseController, which itself subclasses ApplicationController. The base controller enforces the API-specific behavior across all endpoints 3:

• Skips session-based authentication (skip_authentication) and CSRF verification
• Forces JSON format on every request
• Runs authenticate_request!, check_api_key_rate_limit, and log_api_access as before_actions
• Provides shared error handlers for RecordNotFound, ParameterMissing, and scope authorization failures

Web controllers are unaffected — all the above are opt-in only at the Api::V1::BaseController level.

Authentication#

Requests authenticate via one of two mechanisms, tried in order 4:

1. OAuth (Doorkeeper) — Bearer token in the Authorization header. The token is looked up against Doorkeeper::AccessToken and must have read or read_write scope 5. Doorkeeper is configured with a 1-year token expiration, PKCE enforcement, refresh tokens, and SHA256 secret hashing 678.

2. API Key — X-Api-Key header. Keys are stored encrypted (deterministic AES) in the ApiKey model 9 and carry a read or read_write scope 10. Keys track last_used_at and support optional expiration and revocation 11.

Both methods resolve a @current_user and call setup_current_context_for_api, which builds a fresh (unsaved) Session object attached to Current.session — ensuring API requests never inherit web session state or impersonation context 12.

Scope Model#

authorize_scope! enforces this at the controller level; write endpoints call it explicitly 13.

Rate Limiting#

Rate limiting applies to API key authentication only. Limits are enforced via a Redis-backed sliding hourly window 1415:

All keys currently default to standard. Self-hosted deployments use NoopApiRateLimiter (no limiting) 16. Rate limit status is surfaced via X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers 17.

Endpoints#

Routes are declared in config/routes.rb (lines 533–604). The full list of resource controllers under app/controllers/api/v1/ 1:

Auth endpoints (POST /api/v1/auth/signup, /auth/login, /auth/refresh, etc.) are unauthenticated by design 18. The /api/v1/users/me and /users/reset routes provide account self-service 19.

In development, Swagger/Rswag UI is available at /api-docs 20.

OAuth Discovery#

Well-known OAuth metadata endpoints are exposed at the root level 21:

• GET /.well-known/oauth-protected-resource
• GET /.well-known/oauth-authorization-server
• POST /register (dynamic client registration)

Doorkeeper itself is mounted via use_doorkeeper 22.

Key Files#