--- title: "Authentication - DreamFactory Documentation" source: "http://wiki.dreamfactory.com/Authentication" canonical_url: "http://wiki.dreamfactory.com/Authentication" converted_at: "2026-10-22T18:50:39.719Z" format: "markdown" converted_by: "html-to-md-ai" --- []() # Authentication From DreamFactory Wiki [Jump to navigation](#mw-head) [Jump to search](#searchInput) **How to authenticate with DreamFactory — correct login endpoints, API keys, session tokens, and common mistakes.** ## Contents - [1 Authentication](#Authentication) - [1.1 The Two-Credential System](#The_Two-Credential_System) - [1.2 Admin Login (System Administrators)](#Admin_Login_(System_Administrators)) - [1.3 Regular User Login](#Regular_User_Login) - [1.4 Getting the Admin App API Key](#Getting_the_Admin_App_API_Key) - [1.5 Using the Session Token](#Using_the_Session_Token) - [1.6 Refresh / Check Current Session](#Refresh_/_Check_Current_Session) - [1.7 Logout](#Logout) - [1.8 Common Errors and Fixes](#Common_Errors_and_Fixes) - [1.9 Quick Reference — Endpoint Summary](#Quick_Reference_—_Endpoint_Summary) # 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/*` ✅ ✅ Retrieved from "[https://wiki.dreamfactory.com/index.php?title=Authentication&oldid=965](https://wiki.dreamfactory.com/index.php?title=Authentication&oldid=965)" [Categories](/Special:Categories): - [Authentication](/Category:Authentication) - [Session Token](/index.php?title=Category:Session_Token&action=edit&redlink=1) - [Jwt](/index.php?title=Category:Jwt&action=edit&redlink=1) - [API](/Category:API)