Skip to content

Authentication ​

How to authenticate with the GhostAI API.

API Keys ​

Creating an API Key ​

  1. Go to Settings → API Keys
  2. Click "Create API Key"
  3. Name your key (e.g., "Production Server")
  4. Select permissions
  5. 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/chat

Key Types ​

TypePrefixUse Case
Livesk_live_Production
Testsk_test_Development

Permissions ​

API keys can have scoped permissions:

PermissionDescription
chat:writeSend chat messages
chat:readRead chat history
detect:writeRun PII detection
sessions:readList sessions
sessions:writeCreate/delete sessions
export:readGenerate reports
admin:readView admin data
admin:writeModify 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:

ProviderStatusDocumentation
Google✅ AvailableGoogle Cloud Console
GitHub✅ AvailableGitHub Developer Settings
Microsoft✅ AvailableAzure Portal
Apple✅ AvailableApple 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:

IdPStatus
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 ​

  1. Go to Admin Dashboard → Team → SCIM
  2. Generate a bearer token (shown only once)
  3. Copy the SCIM Base URL and token to your IdP

SCIM Endpoints ​

EndpointMethodDescription
/scim/v2/UsersGETList provisioned users
/scim/v2/UsersPOSTCreate (provision) a user
/scim/v2/Users/{id}GETGet user details
/scim/v2/Users/{id}PATCHUpdate user attributes
/scim/v2/Users/{id}DELETEDeprovision 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/Users

Token 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 ​

  1. 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
  1. 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"
  1. Use access token:
bash
curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.ghostai.com/v1/chat

Refresh 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/chat

Magic links provide a passwordless sign-in flow. Clicking the link auto-creates accounts for new users.

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." }
bash
POST /api/auth/magic-link/verify
Content-Type: application/json

{ "code": "abc123..." }

Response: 200 OK with TokenResponse (sets httpOnly cookie)

BehaviorDetail
TTL15 minutes
One-time useCode is deleted on verification
Auto-createUnknown emails get new accounts with email_verified=true
2FA bypassMagic links skip TOTP (email possession = second factor)
Rate limit5 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 ​

  1. POST /api/auth/login with email + password
  2. If MFA enabled: returns HTTP 202 with mfa_token
  3. POST /api/auth/mfa/verify with mfa_token + 6-digit code
  4. Returns TokenResponse with 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 ​

EndpointMethodDescription
/api/auth/mfa/setupPOSTStart MFA setup (returns QR code)
/api/auth/mfa/confirm-setupPOSTConfirm setup with TOTP code
/api/auth/mfa/verifyPOSTVerify TOTP during login
/api/auth/mfaDELETEDisable MFA (requires TOTP code)
/api/auth/mfa/backup-codesPOSTRegenerate backup codes (requires TOTP code)
/api/admin/.../mfaDELETEAdmin: 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.

EndpointLimitWindowKey
POST /auth/login10 requests15 minutesPer IP
POST /auth/login10 failed attempts1 hourPer email
POST /auth/signup5 requests15 minutesPer IP
POST /auth/magic-link5 requests15 minutesPer email
POST /auth/mfa/verify5 attempts5 minutesPer MFA token
POST /auth/forgot-password3 requests15 minutesPer 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 ​

  1. Never expose keys: Don't commit to version control
  2. Use environment variables: Store keys in env vars
  3. Rotate regularly: Change keys periodically
  4. Use minimal permissions: Only grant what's needed
  5. Monitor usage: Review API key usage logs
  6. Use test keys: For development environments

Troubleshooting ​

"Unauthorized" Error ​

  1. Verify key is correct (no extra spaces)
  2. Check key hasn't been revoked
  3. Verify key has required permissions

"Forbidden" Error ​

  1. Check key permissions
  2. Verify resource ownership
  3. Check organization limits

Key Expired ​

OAuth tokens expire. Refresh using the refresh token flow.

SOC 2 Type II Certified | BAA Available | HIPAA-Ready