API Authentication and Authorization#

Sure's programmatic API (/api/v1) supports two authentication methods: OAuth 2.0 Bearer tokens and API keys. Both are handled by Api::V1::BaseController, which skips session-based auth and CSRF, then runs authenticate_request!, check_api_key_rate_limit, and log_api_access as before_actions on every request.

Authentication Flow#

authenticate_request! tries each method in order; the first success sets @current_user and @authentication_method, then calls setup_current_context_for_api to attach a fresh, unsaved Session to Current.session — ensuring API requests never inherit web session state or impersonation context 1.

Request
  └─ authenticate_oauth (Authorization: Bearer <token>)
       └─ on failure → authenticate_api_key (X-Api-Key: <key>)
                         └─ on failure → 401 Unauthorized

OAuth 2.0 (Doorkeeper)#

• Header: Authorization: Bearer <token>
• authenticate_oauth looks up the token via Doorkeeper::AccessToken.by_token, then verifies accessible? and that the token carries at least read or read_write scope.
• Doorkeeper is configured with 1-year token expiration 2, PKCE enforcement for non-confidential clients 3, refresh tokens 4, and SHA256 secret hashing in production 5.
• OAuth discovery endpoints are exposed at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server; dynamic client registration is available at POST /register.

API Keys#

• Header: X-Api-Key: <key>
• authenticate_api_key calls ApiKey.find_by_value, which looks up the key using deterministic AES encryption 6 — enabling indexed lookups without storing plaintext.
• Keys track last_used_at (updated on each request via update_last_used!) and support optional expiration (expires_at) and revocation (revoke!) 7.
• Rate limiting is initialized here: @rate_limiter = ApiRateLimiter.limit(@api_key) 8.

Scope Model#

Both authentication methods use the same two-scope model, enforced by authorize_scope!:

read is the Doorkeeper default scope 9. Write endpoints call authorize_scope!(:write), which requires read_write; attempting a write with only read returns 403 Forbidden with "insufficient_scope".

current_scopes abstracts over both auth methods — returning doorkeeper_token.scopes for OAuth or @api_key.scopes for API keys — so authorize_scope! is auth-method-agnostic.

Rate Limiting (API Keys Only)#

Rate limiting applies only to API key authentication; OAuth tokens are not rate-limited 10.

check_api_key_rate_limit runs after authentication. It uses a Redis-backed sliding hourly window 11:

Rate limit status is surfaced in response headers on every API key request 12:

• X-RateLimit-Limit — the tier ceiling
• X-RateLimit-Remaining — requests left in the current window
• X-RateLimit-Reset — seconds until the window resets
• Retry-After — also set on 429 Too Many Requests responses 13

Self-hosted deployments use NoopApiRateLimiter, which always returns false for rate_limit_exceeded? and Float::INFINITY for the limit 14, effectively disabling rate limiting.

Key Files#