Authentication¶

Secure by design. Multiple authentication methods for different use cases. API keys for development, OAuth for user flows, service accounts for automation.

Authentication Methods¶

API Keys¶

Getting an API Key¶

1. Log in to console.pauhu.ai
2. Navigate to Settings → API Keys
3. Click Create New Key
4. Copy and store securely

Key Types¶

Using API Keys¶

curl https://api.pauhu.ai/v1/translate \
  -H "Authorization: Bearer pk_your_api_key"

curl "https://api.pauhu.ai/v1/translate?api_key=pk_your_api_key"

Key Scopes¶

from pauhu import Pauhu

# Create restricted key with specific scopes
client = Pauhu(api_key="pk_admin_key")

restricted_key = client.api_keys.create(
    name="translation-only",
    scopes=["translate:read", "translate:write"],
    expires_in_days=90
)

Available scopes:

OAuth 2.0¶

For user-facing applications where users grant permission.

Authorization Code Flow¶

sequenceDiagram
    participant User
    participant App
    participant Pauhu

    User->>App: Click "Connect Pauhu"
    App->>Pauhu: Redirect to /oauth/authorize
    Pauhu->>User: Show consent screen
    User->>Pauhu: Grant permission
    Pauhu->>App: Redirect with code
    App->>Pauhu: Exchange code for token
    Pauhu->>App: Access token + refresh token
    App->>Pauhu: API calls with token

Step 1: Redirect to Authorization¶

https://auth.pauhu.ai/oauth/authorize?
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=translate:write+documents:read&
  state=random_state_string

Step 2: Exchange Code for Token¶

curl -X POST https://auth.pauhu.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "code=authorization_code" \
  -d "redirect_uri=https://yourapp.com/callback"

Response¶

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "scope": "translate:write documents:read"
}

Refresh Tokens¶

curl -X POST https://auth.pauhu.ai/oauth/token \
  -d "grant_type=refresh_token" \
  -d "client_id=your_client_id" \
  -d "refresh_token=your_refresh_token"

Service Accounts¶

For server-to-server authentication without user context.

Create Service Account¶

from pauhu import Pauhu

client = Pauhu(api_key="pk_admin_key")

service_account = client.service_accounts.create(
    name="ci-cd-pipeline",
    description="GitHub Actions deployments",
    scopes=["translate:write", "documents:write"]
)

print(service_account.key_file)  # JSON key file

Authenticate with Key File¶

from pauhu import Pauhu

# Using key file
client = Pauhu.from_service_account(
    key_file="/path/to/service-account.json"
)

# Or from environment variable
# PAUHU_SERVICE_ACCOUNT_KEY={"type": "service_account", ...}
client = Pauhu.from_service_account()

SSO/SAML¶

Enterprise single sign-on integration.

Supported Providers¶

• Okta
• Azure AD
• Google Workspace
• OneLogin
• PingIdentity
• Custom SAML 2.0

Configuration¶

Contact enterprise@pauhu.ai for SSO setup.

Required information:

• IdP Metadata URL
• Entity ID
• ACS URL preference
• Attribute mappings

Security Best Practices¶

Environment Variables¶

# .env file (never commit)
PAUHU_API_KEY=pk_your_api_key

# In code
import os
from pauhu import Pauhu

client = Pauhu(api_key=os.environ["PAUHU_API_KEY"])

Key Rotation¶

# Create new key before expiring old one
new_key = client.api_keys.create(name="rotation-2025-01")

# Update your systems to use new key
# ...

# Delete old key
client.api_keys.delete(old_key.id)

IP Allowlisting¶

# Restrict key to specific IPs
client.api_keys.update(
    key_id="key_abc123",
    allowed_ips=["203.0.113.0/24", "198.51.100.42"]
)

Testing Authentication¶

from pauhu import Pauhu

client = Pauhu(api_key="pk_...")

# Verify authentication
info = client.auth.verify()

print(info.authenticated)  # True
print(info.scopes)         # ["translate:write", ...]
print(info.expires_at)     # 2025-12-31T23:59:59Z

# cURL
curl https://api.pauhu.ai/v1/auth/verify \
  -H "Authorization: Bearer pk_..."