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.

What is Gait?

Gait is an identity and security service. It handles everything about who someone is:

• sign-up and login;
• two-factor authentication;
• sessions, logout and "log out everywhere";
• short-lived signed access tokens, and publishing the public keys that let other services check them.

Alongside that, it watches its own security posture (a security observatory with automated investigation).

Apps don't build login themselves. They send people to Gait, and gait-sdk lets their backend trust the result.

Availability: Gait currently serves its own first-party applications (starting with Lumen, a vascular-ultrasound reporting platform). Self-service onboarding for outside applications isn't open yet. You can still try gait-sdk end to end today with the local stand-in issuer in examples/.

New here? Start here

1. Concepts: tokens, signatures, JWKS, revocation, 401 vs 403, in plain language.
2. Examples: a FastAPI and a Django app you can run in five minutes, no account needed.
3. Integration guide: wiring it into your own app.
4. Something wrong? Troubleshooting lists the exact error messages.

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.