gait-sdk

The official Python SDK for Gait, an identity and security platform. Drop it into a Django REST Framework or FastAPI service to verify who is calling you, using identities Gait issues. It never issues tokens, stores passwords, or makes authorization decisions.

Gait                authenticates   — who are you? (login, 2FA, sessions, signed tokens)
gait-sdk            verifies        — is this token genuine, and whose is it?
your application    authorizes      — what may this person do here?

That boundary is the core design rule. The SDK hands your code a verified identity (subject, email, session, token id, issuer). Roles, organizations and permissions belong to your application. See Architecture.

Install

pip install "gait-sdk[django]"     # Django REST Framework services
pip install "gait-sdk[fastapi]"    # FastAPI services
pip install gait-sdk               # core only (verification, sessions, app identity)

Requires Python 3.10+. Pin exact versions in production (gait-sdk==0.5.0). See Supply chain.

Quick start: Django REST Framework

# settings.py
INSTALLED_APPS = [..., "gait_sdk"]          # validates configuration at startup

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": ["gait_sdk.authentication.ExternalJWTAuthentication"],
}

GAIT_TOKEN_VERIFIER = "jwks"                 # verify locally (recommended)
GAIT_JWKS_URL = "https://auth.example.com/.well-known/jwks.json"
GAIT_ISSUER = "https://auth.example.com"
GAIT_AUDIENCE = "urn:gait:your-app"
GAIT_AUTH_URL = "https://auth.example.com/api"   # used for live session checks

# views.py
from gait_sdk.django.authentication import require_live_session

class FinalizeReport(APIView):
    def post(self, request, pk):
        identity = request.verified_identity    # subject, email, session_id, token_id, issuer
        ...                                     # YOUR authorization check first
        require_live_session(request)           # sensitive action: confirm the session live
        ...                                     # then mutate

Quick start: FastAPI

from fastapi import Depends, FastAPI
from gait_sdk.fastapi.dependencies import require_live_session, validate_configuration, verify_token

app = FastAPI()
validate_configuration()   # fail at startup, not on the first request

@app.get("/me")
async def me(claims: dict = Depends(verify_token)):
    return {"subject": claims["id"], "email": claims["email"]}   # "id" works in both verifier modes

@app.post("/danger")
async def danger(claims: dict = Depends(require_live_session)):
    ...

Configuration

Settings come from Django settings first, then environment variables / .env. An invalid or incomplete configuration stops the service at startup.

What you get

Security, in one screen

• RS256 only. alg=none, HS256 key-confusion and unknown algorithms are rejected. iss, aud, exp, iat, sub, sid, jti and token_use="access" are all required.
• The SDK holds no secrets for verification. It only ever has Gait's public keys, so it cannot mint tokens even if compromised.
• Fails closed: an invalid token → 401; Gait unreachable → 503. It never falls back to a weaker check.
• Real 401s (not DRF's silent 403), so clients' refresh-on-401 logic works.
• Revocation: local verification sees a revoked session only when its token expires (≤15 min). Protect sensitive actions with require_live_session.
• No token, cookie or credential value is ever logged.

Full threat model, guarantees, limits and audit history: docs/SECURITY.md. To report a vulnerability, see the same file.

Upgrading from auth_integration

The package was renamed in 0.5.0. The old import name still works as a deprecated alias until 0.6.0, returning the same modules, so nothing breaks while you migrate:

1. pip install gait-sdk (replacing the old git URL pin).
2. Replace auth_integration with gait_sdk in imports, INSTALLED_APPS, and DRF settings strings.

Details: Integration guide.

Documentation

License

MIT, © Anthony Narine.