raqeb 1.0.0
Python SDK for Raqeb Database PAM and Secrets Management
Requires Python: >=3.7

# Raqeb Python SDK

Official Python SDK for Raqeb Database PAM and Secrets Management.

## Installation

```bash
pip install raqeb
```

## Quick Start

```python
from raqeb import RaqebClient

# Initialize client with service account API key
client = RaqebClient(api_key="sa_your_api_key_here")

# Get a secret
secret = client.get_secret("secret-id")
print(f"Secret value: {secret['value']}")

# Get temporary database credentials
creds = client.get_database_credentials(
    database_id="db-id",
    ttl_hours=4,
    access_level="read-only"
)

print(f"Username: {creds['username']}")
print(f"Password: {creds['password']}")
print(f"Expires: {creds['expires_at']}")

# Revoke credentials when done
client.revoke_lease(creds['lease_id'])
```

## Usage Examples

### Secrets Management

```python
from raqeb import RaqebClient

client = RaqebClient(api_key="sa_your_key")

# Retrieve a secret
secret = client.get_secret("api-key-prod")
api_key = secret['value']

# Use the secret in your application
import requests
response = requests.get(
    "https://api.example.com/data",
    headers={"Authorization": f"Bearer {api_key}"}
)
```

### Database Access

```python
from raqeb import RaqebClient
import psycopg2

client = RaqebClient(api_key="sa_your_key")

# Get temporary database credentials
creds = client.get_database_credentials(
    database_id="prod-postgres",
    ttl_hours=2,
    access_level="read-only"
)

# Connect to database
conn = psycopg2.connect(
    host="db.example.com",
    port=5432,
    database="myapp",
    user=creds['username'],
    password=creds['password']
)

try:
    # Use the connection
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM users LIMIT 10")
    results = cursor.fetchall()
    
finally:
    conn.close()
    # Revoke credentials
    client.revoke_lease(creds['lease_id'])
```

### Context Manager

```python
from raqeb import RaqebClient

# Use context manager for automatic cleanup
with RaqebClient(api_key="sa_your_key") as client:
    secret = client.get_secret("secret-id")
    print(secret['value'])
```

### API Key Management

```python
from raqeb import RaqebClient

client = RaqebClient(api_key="sa_your_key")

# List API keys
keys = client.list_api_keys()
for key in keys:
    print(f"{key['name']}: {key['key_prefix']}...")

# Create new API key
new_key = client.create_api_key(
    name="CI/CD Pipeline",
    scopes=["secrets:read", "databases:read"],
    description="Key for automated deployments"
)
print(f"New API Key: {new_key['api_key']}")  # Save this!

# Delete API key
client.delete_api_key("key-id")
```

## Error Handling

```python
from raqeb import RaqebClient, AuthenticationError, PermissionError, NotFoundError

client = RaqebClient(api_key="sa_your_key")

try:
    secret = client.get_secret("secret-id")
    
except AuthenticationError:
    print("Invalid or expired API key")
    
except PermissionError:
    print("Insufficient permissions - check API key scopes")
    
except NotFoundError:
    print("Secret not found")
    
except RaqebError as e:
    print(f"API error: {e}")
```

## API Reference

### RaqebClient

#### `__init__(api_key, base_url="https://app.raqeb.cloud/api/v1")`
Initialize the client.

#### `get_secret(secret_id) -> dict`
Retrieve a secret value.

**Returns:**
```python
{
    'secret_id': 'secret-123',
    'name': 'API Key',
    'value': 'secret-value',
    'retrieved_at': '2026-02-14T16:09:00Z'
}
```

#### `get_database_credentials(database_id, ttl_hours=4, access_level='read-only') -> dict`
Generate temporary database credentials.

**Parameters:**
- `database_id` (str): Database ID
- `ttl_hours` (int): Time to live in hours (default: 4)
- `access_level` (str): 'read-only', 'read-write', or 'admin'

**Returns:**
```python
{
    'lease_id': 'lease-123',
    'username': 'temp_user_abc',
    'password': 'temp_pass_xyz',
    'database_id': 'db-123',
    'access_level': 'read-only',
    'issued_at': '2026-02-14T16:09:00Z',
    'expires_at': '2026-02-14T20:09:00Z',
    'ttl_seconds': 14400
}
```

#### `revoke_lease(lease_id) -> None`
Revoke a dynamic secret lease.

#### `list_api_keys() -> list`
List user's API keys.

#### `create_api_key(name, description=None, scopes=None, expires_at=None) -> dict`
Create a new API key.

#### `delete_api_key(key_id) -> None`
Delete an API key.

## Environment Variables

You can use environment variables for configuration:

```python
import os
from raqeb import RaqebClient

client = RaqebClient(
    api_key=os.getenv('RAQEB_API_KEY'),
    base_url=os.getenv('RAQEB_BASE_URL', 'https://app.raqeb.cloud/api/v1')
)
```

## Best Practices

1. **Never hardcode API keys** - Use environment variables
2. **Use minimal scopes** - Only grant necessary permissions
3. **Set appropriate TTLs** - Use shortest time needed
4. **Always revoke leases** - Clean up credentials when done
5. **Handle errors gracefully** - Catch and handle SDK exceptions
6. **Use context managers** - Automatic resource cleanup

## License

MIT License - see LICENSE file for details

## Support

- Documentation: https://docs.raqeb.cloud
- Email: support@raqeb.cloud
- GitHub: https://github.com/raqeb/python-sdk