Add OAuth2 scopes support for token requests

[Michel Edkrantz (MichelEdkrantz)]

Add support to specify oauth scopes, this allows the user to downgrade their session to for example read only.

Summary

• Adds scopes: Optional[List[str]] parameter to all auth clients (RequestsAuthSession, HttpxAuthAsyncClient), base clients (BaseApiClient, BaseAsyncApiClient, create_session, make_token_provider), and the CLI (--scopes)
• Adds scopes field to ApiCredentials dataclass, parsed from the "scopes" array in credentials.json
• Adds scopes field to Environment dataclass, parsed from environments.json — this is the primary place to configure scopes
• Scopes resolution order: explicit parameter/--scopes > environment config > credentials file
• from_env() on both sync and async base clients passes environment scopes to the constructor
• Token cache keys now include a hashed scope string to prevent serving cached tokens with wrong scopes

Examples

Environment config (recommended)

{
  "environments": {
    "production": {
      "host": "app.kognic.com",
      "auth_server": "https://auth.app.kognic.com",
      "credentials": "keyring://production",
      "scopes": ["api:read", "api:write"]
    }
  }
}

CLI

# Scopes from environment config are used automatically
kognic-auth get-access-token --env production

# Override with explicit scopes
kognic-auth get-access-token --env production --scopes custom:scope

Python clients

# Picks up scopes from environment config
client = MyApiClient.from_env("production")

# Explicit scopes (overrides everything)
client = MyApiClient(auth="creds.json", scopes=["api:read"])

# Async
async with MyAsyncApiClient.from_env("production") as client:
    ...

Credentials file (fallback)

{
  "clientId": "...",
  "clientSecret": "...",
  "scopes": ["api:read", "api:write"]
}

Scopes here are only used when no scopes are set in the environment config or passed explicitly.

Test plan

• All 210 tests pass (including new tests for env scopes)
• ruff check and format clean
• Pre-commit hooks pass
• Manually test kognic-auth get-access-token --scopes api:read api:write
• Manually test with environments.json containing "scopes": ["api:read", "api:write"]
• Manually test that environment scopes override credential scopes
• Manually test that --scopes overrides environment scopes

🤖 Generated with Claude Code