Appearance
Authentication
How to authenticate with the GhostAI API.
API Keys
Creating an API Key
- Go to Settings → API Keys
- Click "Create API Key"
- Name your key (e.g., "Production Server")
- Select permissions
- Copy and securely store the key
WARNING
API keys are shown only once. Store them securely.
Using API Keys
Include the key in the Authorization header:
bash
curl -H "Authorization: Bearer sk_live_abc123..." \
https://api.ghostai.com/v1/chatKey Types
| Type | Prefix | Use Case |
|---|---|---|
| Live | sk_live_ | Production |
| Test | sk_test_ | Development |
Permissions
API keys can have scoped permissions:
| Permission | Description |
|---|---|
chat:write | Send chat messages |
chat:read | Read chat history |
detect:write | Run PII detection |
sessions:read | List sessions |
sessions:write | Create/delete sessions |
export:read | Generate reports |
admin:read | View admin data |
admin:write | Modify settings |
Example: Limited Key
Create a key with only chat permissions:
json
{
"name": "Chat Bot",
"permissions": ["chat:write", "chat:read"]
}Social Login (OAuth/OIDC)
GhostAI supports social login via multiple OAuth providers:
| Provider | Status | Documentation |
|---|---|---|
| ✅ Available | Google Cloud Console | |
| GitHub | ✅ Available | GitHub Developer Settings |
| Microsoft | ✅ Available | Azure Portal |
| Apple | ✅ Available | Apple Developer |
Configure providers in your .env file or AWS Secrets Manager for production deployments.
SAML SSO (Enterprise)
Enterprise customers can configure SAML SSO via the Admin Dashboard:
| IdP | Status |
|---|---|
| Okta | ✅ Supported |
| Azure AD / Entra ID | ✅ Supported |
| OneLogin | ✅ Supported |
| Google Workspace | ✅ Supported |
SCIM 2.0 Provisioning (Enterprise)
Automate user lifecycle management from your Identity Provider:
Setup
- Go to Admin Dashboard → Team → SCIM
- Generate a bearer token (shown only once)
- Copy the SCIM Base URL and token to your IdP
SCIM Endpoints
| Endpoint | Method | Description |
|---|---|---|
/scim/v2/Users | GET | List provisioned users |
/scim/v2/Users | POST | Create (provision) a user |
/scim/v2/Users/{id} | GET | Get user details |
/scim/v2/Users/{id} | PATCH | Update user attributes |
/scim/v2/Users/{id} | DELETE | Deprovision a user |
SCIM Authentication
SCIM endpoints use bearer token authentication:
bash
curl -H "Authorization: Bearer scim_your_token_here" \
https://api.ghostai.com/scim/v2/UsersToken Management
bash
# Generate a SCIM token
POST /api/organizations/{org_id}/scim-tokens
{ "description": "Okta SCIM integration" }
# List active tokens
GET /api/organizations/{org_id}/scim-tokens
# Revoke a token
DELETE /api/organizations/{org_id}/scim-tokens/{token_id}OAuth 2.0
For user-level authentication:
Authorization Code Flow
- Redirect user to authorize:
https://auth.ghostai.com/oauth/authorize?
client_id=YOUR_CLIENT_ID&
redirect_uri=https://yourapp.com/callback&
response_type=code&
scope=chat:write- Exchange code for token:
bash
curl -X POST https://auth.ghostai.com/oauth/token \
-d "grant_type=authorization_code" \
-d "code=AUTH_CODE" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET"- Use access token:
bash
curl -H "Authorization: Bearer ACCESS_TOKEN" \
https://api.ghostai.com/v1/chatRefresh Tokens
bash
curl -X POST https://auth.ghostai.com/oauth/token \
-d "grant_type=refresh_token" \
-d "refresh_token=REFRESH_TOKEN" \
-d "client_id=YOUR_CLIENT_ID"JWT Authentication
For service-to-service:
Generate JWT
python
import jwt
import time
payload = {
"iss": "your-service",
"sub": "service-account-id",
"aud": "ghostai-api",
"iat": int(time.time()),
"exp": int(time.time()) + 3600
}
token = jwt.encode(payload, private_key, algorithm="RS256")Use JWT
bash
curl -H "Authorization: Bearer JWT_TOKEN" \
https://api.ghostai.com/v1/chatPasswordless Magic Links
Magic links provide a passwordless sign-in flow. Clicking the link auto-creates accounts for new users.
Request a Magic Link
bash
POST /api/auth/magic-link
Content-Type: application/json
{ "email": "user@example.com" }Response: 200 OK (always, to prevent email enumeration)
json
{ "success": true, "message": "If an account with that email exists, a sign-in link has been sent." }Verify a Magic Link
bash
POST /api/auth/magic-link/verify
Content-Type: application/json
{ "code": "abc123..." }Response: 200 OK with TokenResponse (sets httpOnly cookie)
| Behavior | Detail |
|---|---|
| TTL | 15 minutes |
| One-time use | Code is deleted on verification |
| Auto-create | Unknown emails get new accounts with email_verified=true |
| 2FA bypass | Magic links skip TOTP (email possession = second factor) |
| Rate limit | 5 requests per email per 15 minutes |
Two-Factor Authentication (TOTP)
TOTP 2FA adds a second factor via authenticator apps (Google Authenticator, Authy, 1Password).
Login Flow with MFA
POST /api/auth/loginwith email + password- If MFA enabled: returns HTTP 202 with
mfa_token POST /api/auth/mfa/verifywithmfa_token+ 6-digit code- Returns
TokenResponsewith session cookie
bash
# Step 1: Login returns 202
POST /api/auth/login
{ "email": "user@example.com", "password": "..." }
# Response (202 Accepted):
{ "mfa_required": true, "mfa_token": "abc123..." }
# Step 2: Verify TOTP
POST /api/auth/mfa/verify
{ "mfa_token": "abc123...", "code": "123456" }MFA Setup
bash
# Start setup (requires authentication)
POST /api/auth/mfa/setup
# Response:
{
"secret": "JBSWY3DPEHPK3PXP",
"otpauth_url": "otpauth://totp/GhostAI:user@example.com?...",
"qr_code_data_uri": "data:image/png;base64,..."
}
# Confirm with a code from authenticator app
POST /api/auth/mfa/confirm-setup
{ "code": "123456" }
# Response: one-time display of backup codes
{ "backup_codes": ["a1b2c3d4", "e5f6g7h8", ...] }MFA Management
| Endpoint | Method | Description |
|---|---|---|
/api/auth/mfa/setup | POST | Start MFA setup (returns QR code) |
/api/auth/mfa/confirm-setup | POST | Confirm setup with TOTP code |
/api/auth/mfa/verify | POST | Verify TOTP during login |
/api/auth/mfa | DELETE | Disable MFA (requires TOTP code) |
/api/auth/mfa/backup-codes | POST | Regenerate backup codes (requires TOTP code) |
/api/admin/.../mfa | DELETE | Admin: force-disable user MFA |
Backup Codes
Each user gets 10 backup codes on MFA setup. Codes are:
- 8-character hex strings
- Stored as bcrypt hashes (server never sees plaintext after display)
- One-time use (consumed on verification)
- Regeneratable via TOTP verification
Rate Limiting
All authentication endpoints are rate-limited to prevent brute-force attacks.
| Endpoint | Limit | Window | Key |
|---|---|---|---|
POST /auth/login | 10 requests | 15 minutes | Per IP |
POST /auth/login | 10 failed attempts | 1 hour | Per email |
POST /auth/signup | 5 requests | 15 minutes | Per IP |
POST /auth/magic-link | 5 requests | 15 minutes | Per email |
POST /auth/mfa/verify | 5 attempts | 5 minutes | Per MFA token |
POST /auth/forgot-password | 3 requests | 15 minutes | Per IP |
Rate limit exceeded response:
HTTP/1.1 429 Too Many Requests
Retry-After: 847
{ "detail": "Too many requests, try again later" }Security Best Practices
- Never expose keys: Don't commit to version control
- Use environment variables: Store keys in env vars
- Rotate regularly: Change keys periodically
- Use minimal permissions: Only grant what's needed
- Monitor usage: Review API key usage logs
- Use test keys: For development environments
Troubleshooting
"Unauthorized" Error
- Verify key is correct (no extra spaces)
- Check key hasn't been revoked
- Verify key has required permissions
"Forbidden" Error
- Check key permissions
- Verify resource ownership
- Check organization limits
Key Expired
OAuth tokens expire. Refresh using the refresh token flow.