Authentication and Authorisation

Who are you, and what may you do?

Authentication proves identity; authorisation decides what that identity may do. API keys are simple for server-to-server access and identify an application, but they are long-lived secrets: send them in a header (never in the URL), allow rotation and revocation, and scope them. OAuth 2.0 (with OpenID Connect for login) is the standard when users grant a third-party app limited access to their data: short-lived access tokens with scopes (orders:read) and refresh tokens; use the authorisation-code flow with PKCE for apps. JWTs are signed tokens that carry claims; validate signature, issuer, audience and expiry on every call. Always use HTTPS, check authorisation on every request on the server, and return 401 or 403 appropriately.

Verify, limit, minimise

Authenticate every caller, check every object access and expose only what is needed.

Scopes in an OpenAPI security scheme (illustrative)

Scopes let a token be limited to the operations a client really needs.

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            orders:read: Read orders
            orders:write: Create and change orders
security:
  - oauth2: [orders:read]

Never put secrets in URLs

URLs end up in logs, browser history and referrer headers. Send tokens in the Authorization header, not in query strings.

Quick check: Where should an access token be sent?

• In the URL query string
• In the Authorization header over HTTPS
• In the page title
• In a public repository