Metadata-Version: 2.4
Name: cred-auth
Version: 1.0.0
Summary: Cred — credential delegation SDK for AI agents
Project-URL: Homepage, https://cred.ninja
Project-URL: Repository, https://github.com/cred-ninja/sdk
Project-URL: Documentation, https://docs.cred.ninja
Author-email: Cred <hello@cred.ninja>
License: Apache-2.0
Keywords: ai-agents,cred,credentials,delegation,oauth
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: cryptography>=42.0
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: hatchling; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# cred-auth

Python SDK for Cred. OAuth2 credential delegation for AI agents. Tokens are brokered, never exposed.

## Install

```bash
pip install cred-auth
```

## Quick Start

```python
import os
from cred import Cred, ConsentRequiredError

cred = Cred(agent_token=os.environ["CRED_AGENT_TOKEN"])

try:
    result = cred.delegate(
        service="google",
        user_id="user_123",
        app_client_id="my_app_client_id",
        scopes=["calendar.readonly"],
    )
    print(result.access_token)
except ConsentRequiredError as e:
    # Redirect user to e.consent_url to complete OAuth consent
    print(f"Redirect user to: {e.consent_url}")
```

## API

### `Cred(agent_token, base_url=...)`

### `delegate(service, user_id, app_client_id, scopes=None) → DelegationResult`

Get a delegated access token for a service on behalf of a user.

Raises `ConsentRequiredError` (with `.consent_url`) if the user hasn't connected the service.

### `get_user_connections(user_id, app_client_id=None) → list[Connection]`

List all active service connections for a user.

### `get_consent_url(service, user_id, app_client_id, scopes, redirect_uri) → str`

Build a consent URL. Pure URL construction, no HTTP call.

### `revoke(service, user_id, app_client_id=None) → None`

Revoke a user's connection to a service.

## Context Manager

```python
with Cred(agent_token=token) as cred:
    result = cred.delegate(service="github", user_id="u1", app_client_id="app1")
```

## Self-Hosted Server Mode

Point `base_url` at your own `@credninja/server` deployment when you want a separate credential broker instead of local-only usage.
