Decube Auth SDK (Python)

The Decube Auth SDK is a lightweight Python client for interacting with the Decube authentication system through the Decube Gateway.

It provides a simple, ergonomic interface for:

• User signup
• User login
• Refresh token rotation

The SDK is intentionally thin and stateless.

---

Installation

From PyPI:

pip install decube-auth

For local development:

pip install -e .

Quick Start

from decube_auth import AuthClient

auth = AuthClient(api_key="dc_live_xxx")

# Signup
tokens = auth.signup("user@example.com", "password123")

# Login
tokens = auth.login("user@example.com", "password123")

# Refresh access token
tokens = auth.refresh(tokens["refresh_token"])

Authentication Model

• API key is used to authenticate the project
• User credentials authenticate the user
• Project context is enforced by the Gateway
• Tokens returned are scoped to a single project
• The SDK communicates only with the Gateway, never directly with backend services.

Public API

AuthClient

Initialization

AuthClient(api_key: str, base_url: str = DEFAULT_BASE_URL)

api_key (required): Project API key base_url (optional): Gateway base URL

signup(email, password)

Creates a new user scoped to the project.

tokens = auth.signup("user@example.com", "password123")

Returns:

{
  "access_token": "...",
  "refresh_token": "..."
}

login(email, password)

Authenticates an existing user.

tokens = auth.login("user@example.com", "password123")

Returns:

{
  "access_token": "...",
  "refresh_token": "..."
}

refresh(refresh_token)

Rotates the refresh token and returns a new token pair.

tokens = auth.refresh(refresh_token)

Returns:

{
  "access_token": "...",
  "refresh_token": "..."
}

Refresh tokens are:

• Single-use
• Rotated on every refresh
• Invalid after use or expiry

Exceptions

• The SDK raises clean, Python-level exceptions instead of exposing HTTP details.
• Exception Meaning
• AuthenticationError Invalid credentials or token
• ConflictError Resource already exists (e.g. duplicate signup)
• BadRequestError Invalid request payload
• ServerError Unexpected server error

Example:

from decube_auth.exceptions import AuthenticationError

try:
    auth.login("a@b.com", "wrong-password")
except AuthenticationError:
    print("Invalid credentials")

Configuration

Base URL By default, the SDK connects to:

http://localhost:7000

Override using environment variable:

DECUBE_BASE_URL=http://your-gateway-host

Or directly in code:

auth = AuthClient(
    api_key="dc_live_xxx",
    base_url="https://api.decube.io"
)

What the SDK Does NOT Do

• Store tokens
• Auto-refresh tokens
• Validate JWTs
• Implement business logic
• Manage sessions

These responsibilities belong to the client application.

Design Principles

• Stateless
• Explicit
• Minimal surface area
• No hidden behavior
• Gateway-centric communication

Status

• 🔒 Frozen at Checkpoint-2
• Public API is locked
• Behavior is stable
• Backward compatibility guaranteed within version range

Summary

The Decube Auth SDK is a convenience layer, not a framework. It exists to make authentication with Decube:

• Easy to integrate
• Predictable
• Explicit

If you understand HTTP, you understand this SDK.