Metadata-Version: 2.5
Name: vallkey
Version: 0.4.0
Summary: Vallkey runtime integration for supported Python HTTP clients.
Project-URL: Homepage, https://vallkey.com
Project-URL: Documentation, https://vallkey.com/docs/python/
Project-URL: Source, https://github.com/vallkeyhq/developer-tools/tree/main/python
Project-URL: Issues, https://github.com/vallkeyhq/developer-tools/issues
Author: Vallkey
License-Expression: MIT
License-File: LICENSE
Keywords: anthropic,api-keys,openai,secrets,security,stripe
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown

![Vallkey python](https://raw.githubusercontent.com/vallkeyhq/developer-tools/main/assets/covers/python.png)

# vallkey

Route ghost-key requests through [Vallkey](https://vallkey.com) using the supported HTTP clients below.

Vallkey gives you ghost keys: stand-in API keys that only work within your rules, and that you can kill in one click. This package sends every request that carries a ghost key to Vallkey instead of the provider, with the same path, so supported clients do not need a base URL override. Requests without a ghost key are not touched.

```sh
pip install vallkey
```

That is all: once it is installed in the app's environment, it turns on when Python starts, with no import and no variable. Requests without a ghost key are left alone. `VALLKEY_AUTO=0` turns it off, also from a `.env` file your app loads, since each request checks it.

**On AWS Lambda, add one line.** Lambda adds your code and layers to Python's path after Python has started, so the package cannot turn itself on there and the ghost key goes straight to the provider, which refuses it. Make this the first line of your handler file:

```python
import vallkey.auto
```

`npx vallkey connect` adds it for you in SAM and Serverless Framework projects.

Put your ghost key where the real key was (for example `OPENAI_API_KEY=gk_openai_...`) and use the SDK as usual:

```python
from openai import OpenAI

client = OpenAI()  # no base_url needed
```

It covers httpx and httpx2 (OpenAI, Anthropic and most new SDKs), requests (Stripe, Twilio and most others), urllib3 on its own (SDKs generated by OpenAPI Generator), botocore (boto3, including S3 buckets named in the address), aiohttp and urllib. Libraries imported later are covered too, so the order of imports does not matter.

| Variable          |                                                      |
| ----------------- | ---------------------------------------------------- |
| `VALLKEY_AUTO=0`  | Turns it off                                         |
| `VALLKEY_API`     | The Vallkey server, if not `https://api.vallkey.com` |
| `VALLKEY_DEBUG=1` | Logs each request sent to Vallkey (never the key)    |

To set up ghost keys from your `.env` files, use the command line tool: `npx vallkey init`.

Docs: https://vallkey.com/docs/python/

## Web pages and mobile apps (short-lived keys)

Keep the ghost key on your server, and give each signed-in user a short-lived key instead. It expires in minutes and can only do what the ghost key allows.

```python
from vallkey.session import create_session_key  # reads VALLKEY_GHOST_KEY

key = create_session_key(user=user.id, ttl_seconds=900)["session_key"]
# send key to the page or app
```

See https://vallkey.com/docs/browsers/.

## Compatibility and security

Read the [transport boundaries](https://github.com/vallkeyhq/developer-tools/blob/main/docs/compatibility.md) and [security policy](../SECURITY.md). Local transport tests do not certify every SDK version or cloud deployment. Use a dedicated key and verify requests from the actual application after deployment.
