Authentication

Learn how to authenticate with Mandatum using API keys and OAuth.

API Keys

API keys are the recommended way to authenticate programmatic access to Mandatum.

Creating an API Key

1. Log in to mandatum.netlify.app
2. Navigate to Settings → API Keys
3. Click Create New API Key
4. Give your key a descriptive name (e.g., "Production Backend")
5. Set an expiration date (optional)
6. Click Create
7. Copy the key immediately - it won't be shown again

Using API Keys

Environment Variables

Store your API key in an environment variable:

export MANDATUM_API_KEY="mdt_live_abc123..."

Python

import os
from mandatum import Mandatum

client = Mandatum(api_key=os.environ.get("MANDATUM_API_KEY"))

TypeScript

Coming Soon

A TypeScript/JavaScript SDK is in development. For now, use the REST API directly.

REST API

Include your API key in the Authorization header:

curl -H "Authorization: Bearer mdt_live_abc123..." \
  https://mandatum-api.gavelinivar.com/api/v1/prompts

Key Types

Mandatum supports two types of API keys:

Type	Prefix	Permissions	Use Case
Live	mdt_live_	Full read/write access	Production applications
Test	mdt_test_	Sandbox environment only	Development and testing

WARNING

Use test keys for development. They don't incur LLM costs but have rate limits.

Rotating Keys

To rotate an API key:

1. Create a new API key
2. Update your application with the new key
3. Verify the new key works
4. Delete the old key

Revoking Keys

To revoke a compromised key:

1. Navigate to Settings → API Keys
2. Find the key to revoke
3. Click Delete
4. Confirm deletion

DANGER

Revoked keys stop working immediately. Update your applications before revoking.

OAuth (Web Applications)

Use OAuth for user-facing applications where users need to log in.

Google OAuth

Mandatum uses Google OAuth 2.0 for user authentication.

Flow

1. User clicks "Sign in with Google"
2. User authorizes your application
3. Mandatum redirects back with an authorization code
4. Exchange code for access token
5. Use token to make API requests

Example (Python/FastAPI)

from fastapi import FastAPI, Depends
from fastapi.security import OAuth2AuthorizationCodeBearer

oauth2_scheme = OAuth2AuthorizationCodeBearer(
    authorizationUrl="https://accounts.google.com/o/oauth2/auth",
    tokenUrl="https://oauth2.googleapis.com/token"
)

app = FastAPI()

@app.get("/auth/callback")
async def auth_callback(code: str):
    # Exchange code for token
    token = await exchange_code_for_token(code)
    return {"access_token": token}

Example (TypeScript/Next.js)

import { useSession, signIn, signOut } from 'next-auth/react';

export default function LoginButton() {
  const { data: session } = useSession();

  if (session) {
    return (
      <>
        Signed in as {session.user.email} <br />
        <button onClick={() => signOut()}>Sign out</button>
      </>
    );
  }

  return <button onClick={() => signIn('google')}>Sign in with Google</button>;
}

Team Access

Manage team member access levels:

Role	Permissions
Admin	Full access, billing, team management
Developer	Create/edit prompts, view logs, manage integrations
Viewer	Read-only access to prompts and logs

Adding Team Members

1. Navigate to Settings → Team
2. Click Invite Member
3. Enter email address and select role
4. Click Send Invitation

Rate Limits

API rate limits apply per API key:

Plan	Requests/Minute	Requests/Day
Free	60	1,000
Pro	600	100,000
Enterprise	Custom	Custom

When rate limited, you'll receive a 429 Too Many Requests response.

Security Best Practices

• Never commit API keys to version control
• Use environment variables or secret management tools
• Rotate keys regularly (every 90 days recommended)
• Use separate keys for dev, staging, and production
• Monitor API key usage in the dashboard
• Revoke unused or old keys
• Use the principle of least privilege for team members

Next Steps

• Learn about managing prompts
• Explore the API reference
• Set up custom integrations