Authentication

From DreamFactory Wiki
Jump to navigation Jump to search

How to authenticate with DreamFactory — correct login endpoints, API keys, session tokens, and common mistakes.

Authentication

The Two-Credential System

Every DreamFactory request needs both:

Header Purpose Where to get it
X-DreamFactory-API-Key Identifies the app Admin UI → Apps, or via tinker
X-DreamFactory-Session-Token Identifies the logged-in user Returned by login endpoint

The API key alone is enough for some public endpoints. Most operations require both.


Admin Login (System Administrators)

POST /api/v2/system/admin/session

⚠️ This is the only correct endpoint for admin users. The following will NOT work: - /api/v2/admin/session → returns "JWT required" error - /api/v2/user/session → returns "missing required email" error - Any of the above without X-DreamFactory-API-Key header

Required headers:

Content-Type: application/json
X-DreamFactory-API-Key: <admin-app-api-key>

Request body:

{
  "email": "[email protected]",
  "password": "yourpassword"
}

Full working example:

curl -s -X POST http://your-df-host/api/v2/system/admin/session \
  -H "Content-Type: application/json" \
  -H "X-DreamFactory-API-Key: YOUR_ADMIN_APP_API_KEY" \
  -d '{"email":"[email protected]","password":"yourpassword"}'

Response:

{
  "session_token": "eyJ0eXAiOiJKV1Qi...",
  "session_id": "eyJ0eXAiOiJKV1Qi...",
  "id": 1,
  "name": "Admin User",
  "email": "[email protected]",
  "is_sys_admin": true,
  "last_login_date": "2026-02-18 19:45:18",
  "token_expiry_date": "2026-02-19 19:45:18"
}

Save the session_token — use it as X-DreamFactory-Session-Token in all subsequent requests.


Regular User Login

POST /api/v2/user/session

Same pattern as admin login. Requires Content-Type: application/json and X-DreamFactory-API-Key.

curl -s -X POST http://your-df-host/api/v2/user/session \
  -H "Content-Type: application/json" \
  -H "X-DreamFactory-API-Key: YOUR_APP_API_KEY" \
  -d '{"email":"[email protected]","password":"yourpassword"}'

Getting the Admin App API Key

The admin app is created automatically on first setup. Three ways to get its key:

Via artisan tinker (server access):

sudo docker exec -i df-docker-web-1 php artisan tinker <<'EOF'
echo \DreamFactory\Core\Models\App::where('name','admin')->first()->api_key;
EOF

Via API (once you have a session):

curl -s http://your-df-host/api/v2/system/app \
  -H "X-DreamFactory-API-Key: YOUR_KEY" \
  -H "X-DreamFactory-Session-Token: YOUR_TOKEN" | python3 -m json.tool

Via Admin UI: Apps → admin → copy API Key field.


Using the Session Token

Include both headers on all subsequent requests:

curl -s http://your-df-host/api/v2/system/service \
  -H "X-DreamFactory-API-Key: YOUR_ADMIN_APP_API_KEY" \
  -H "X-DreamFactory-Session-Token: YOUR_SESSION_TOKEN"

Tokens expire after 24 hours by default. Re-POST to the login endpoint to refresh.


Refresh / Check Current Session

# GET refreshes the token and returns current user info
curl -s -X GET http://your-df-host/api/v2/system/admin/session \
  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \
  -H "X-DreamFactory-Session-Token: YOUR_SESSION_TOKEN"

Logout

curl -s -X DELETE http://your-df-host/api/v2/system/admin/session \
  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \
  -H "X-DreamFactory-Session-Token: YOUR_SESSION_TOKEN"

Common Errors and Fixes

Error Cause Fix
Login request is missing required email Wrong endpoint (user/session for admin) or missing Content-Type header Use POST /api/v2/system/admin/session with Content-Type: application/json
No session token (JWT) provided Using /api/v2/admin/session (wrong endpoint) Use /api/v2/system/admin/session
No session token or API Key detected Missing X-DreamFactory-API-Key header Add the admin app's API key header
Invalid credentials supplied Wrong password, or password set without DF's model (raw bcrypt won't match) Reset via php artisan tinker using the DF User model — it handles hashing
401 Unauthorized Expired or invalid session token Re-authenticate to get a new token

Quick Reference — Endpoint Summary

Action Method Endpoint Needs API Key Needs Session Token
Admin login POST /api/v2/system/admin/session ✅ ❌
User login POST /api/v2/user/session ✅ ❌
Check/refresh session GET /api/v2/system/admin/session ✅ ✅
Logout DELETE /api/v2/system/admin/session ✅ ✅
Any system operation * /api/v2/system/* ✅ ✅
Any data operation * /api/v2/{service}/_table/* ✅ ✅