---
title: "System API - DreamFactory Documentation"
source: "http://wiki.dreamfactory.com/System_Api"
canonical_url: "http://wiki.dreamfactory.com/System_Api"
converted_at: "2026-10-22T18:50:40.840Z"
format: "markdown"
converted_by: "html-to-md-ai"
---
[]()
	
	
	
	# System Api

	
		From DreamFactory Wiki
		
		
		
		
		[Jump to navigation](#mw-head)
		[Jump to search](#searchInput)
		**Complete reference for the DreamFactory System API — managing admins, users, apps, roles, services, and sessions. Derived from live OpenAPI spec at /api/v2/api_docs/system.**

## Contents

- [1 System API](#System_API)

- [1.1 Session Management](#Session_Management)

- [1.1.1 POST /api/v2/system/admin/session — Login](#POST_/api/v2/system/admin/session_—_Login)

- [1.1.2 GET /api/v2/system/admin/session — Refresh / Check](#GET_/api/v2/system/admin/session_—_Refresh_/_Check)

- [1.1.3 PUT /api/v2/system/admin/session — Refresh via token param](#PUT_/api/v2/system/admin/session_—_Refresh_via_token_param)

- [1.1.4 DELETE /api/v2/system/admin/session — Logout](#DELETE_/api/v2/system/admin/session_—_Logout)

- [1.2 Admin Management](#Admin_Management)

- [1.2.1 GET /api/v2/system/admin](#GET_/api/v2/system/admin)

- [1.2.2 POST /api/v2/system/admin](#POST_/api/v2/system/admin)

- [1.2.3 PATCH /api/v2/system/admin/{id} — Update Admin](#PATCH_/api/v2/system/admin/{id}_—_Update_Admin)

- [1.2.4 DELETE /api/v2/system/admin/{id} — Delete Admin](#DELETE_/api/v2/system/admin/{id}_—_Delete_Admin)

- [1.2.5 POST /api/v2/system/admin/password — Change Password](#POST_/api/v2/system/admin/password_—_Change_Password)

- [1.2.6 GET/POST /api/v2/system/admin/profile — Get/Update Profile](#GET/POST_/api/v2/system/admin/profile_—_Get/Update_Profile)

- [1.3 User Management](#User_Management)

- [1.3.1 GET /api/v2/system/user](#GET_/api/v2/system/user)

- [1.3.2 POST /api/v2/system/user](#POST_/api/v2/system/user)

- [1.3.3 PATCH /api/v2/system/user/{id}](#PATCH_/api/v2/system/user/{id})

- [1.3.4 DELETE /api/v2/system/user/{id}](#DELETE_/api/v2/system/user/{id})

- [1.4 App Management](#App_Management)

- [1.4.1 GET /api/v2/system/app — List Apps](#GET_/api/v2/system/app_—_List_Apps)

- [1.4.2 POST /api/v2/system/app — Create App](#POST_/api/v2/system/app_—_Create_App)

- [1.4.3 PATCH /api/v2/system/app/{id}](#PATCH_/api/v2/system/app/{id})

- [1.4.4 DELETE /api/v2/system/app/{id}](#DELETE_/api/v2/system/app/{id})

- [1.5 Service Management](#Service_Management)

- [1.5.1 GET /api/v2/system/service — List Services](#GET_/api/v2/system/service_—_List_Services)

- [1.5.2 POST /api/v2/system/service — Create Service](#POST_/api/v2/system/service_—_Create_Service)

- [1.5.3 PATCH /api/v2/system/service/{id}](#PATCH_/api/v2/system/service/{id})

- [1.5.4 DELETE /api/v2/system/service/{id}](#DELETE_/api/v2/system/service/{id})

- [1.6 Role Management](#Role_Management)

- [1.6.1 GET /api/v2/system/role — List Roles](#GET_/api/v2/system/role_—_List_Roles)

- [1.6.2 POST /api/v2/system/role — Create Role](#POST_/api/v2/system/role_—_Create_Role)

- [1.6.3 PATCH /api/v2/system/role/{id}](#PATCH_/api/v2/system/role/{id})

- [1.6.4 DELETE /api/v2/system/role/{id}](#DELETE_/api/v2/system/role/{id})

- [1.7 CORS Configuration](#CORS_Configuration)

- [1.7.1 GET /api/v2/system/cors — List CORS Rules](#GET_/api/v2/system/cors_—_List_CORS_Rules)

- [1.7.2 POST /api/v2/system/cors — Create CORS Rule](#POST_/api/v2/system/cors_—_Create_CORS_Rule)

- [1.7.3 PATCH /api/v2/system/cors/{id}](#PATCH_/api/v2/system/cors/{id})

- [1.7.4 DELETE /api/v2/system/cors/{id}](#DELETE_/api/v2/system/cors/{id})

- [1.8 Other System Endpoints](#Other_System_Endpoints)

- [1.9 Common Query Parameters (all list endpoints)](#Common_Query_Parameters_(all_list_endpoints))

- [1.10 Response Envelope](#Response_Envelope)

# System API

> All endpoints below are prefixed with `/api/v2/system/`. Every request requires `X-DreamFactory-API-Key`. Most require `X-DreamFactory-Session-Token` as well. See [Authentication](/Authentication).
>
>
>

> **LLM tip:** Retrieve the live OpenAPI spec for this service at `GET /api/v2/api_docs/system` (DF 7.4.x) or `GET /api/v2/system/_spec` (DF 7.5+). Always check the live spec first — it's the ground truth. See [API Discovery](/Api_Generation_And_Connections/Api_Discovery).
>
>
>

---

## Session Management

### `POST /api/v2/system/admin/session` — Login

The correct admin login endpoint. Do NOT use `/api/v2/admin/session` or `/api/v2/user/session`.

**Required headers:** `Content-Type: application/json`, `X-DreamFactory-API-Key`

**Request schema:**

```
{
  "email": "string (required)",
  "password": "string (required)",
  "duration": "integer (optional, session duration in minutes, 0 = until browser close)"
}

```

**Response schema:**

```
{
  "session_token": "string — use as X-DreamFactory-Session-Token",
  "session_id": "string — same as session_token",
  "id": "integer",
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "name": "string",
  "is_sys_admin": "boolean",
  "role": "string",
  "last_login_date": "string",
  "token_expiry_date": "string",
  "apps": "array",
  "ticket": "string",
  "ticket_expiry": "string"
}

```

**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 @login.json   # {"email":"[email protected]","password":"yourpassword"}

```

> ⚠️ Shell quoting issues with `-d '...'` can silently break JSON parsing. Use `-d @file.json` for reliability.
>
>
>

### `GET /api/v2/system/admin/session` — Refresh / Check

Refreshes the current session token. Returns current user info.

### `PUT /api/v2/system/admin/session` — Refresh via token param

Pass `session_token` as query param or `X-DreamFactory-Session-Token` header to refresh a specific token.

### `DELETE /api/v2/system/admin/session` — Logout

Destroys the current session.

---

## Admin Management

### `GET /api/v2/system/admin`

List all system administrators.

**Query params:** `fields`, `related`, `ids`, `filter`, `limit`, `offset`, `order`, `include_count`

```
curl -s http://your-df-host/api/v2/system/admin \
  -H "X-DreamFactory-API-Key: KEY" \
  -H "X-DreamFactory-Session-Token: TOKEN"

```

### `POST /api/v2/system/admin`

Create one or more admins.

**Request schema:**

```
{
  "resource": [{
    "name": "string (required)",
    "email": "string (required)",
    "first_name": "string",
    "last_name": "string",
    "username": "string",
    "phone": "string",
    "is_active": "boolean",
    "default_app_id": "integer"
  }]
}

```

### `PATCH /api/v2/system/admin/{id}` — Update Admin

### `DELETE /api/v2/system/admin/{id}` — Delete Admin

### `POST /api/v2/system/admin/password` — Change Password

### `GET/POST /api/v2/system/admin/profile` — Get/Update Profile

---

## User Management

Non-admin users. Same pattern as admin endpoints.

### `GET /api/v2/system/user`

### `POST /api/v2/system/user`

**Request schema:**

```
{
  "resource": [{
    "name": "string (required)",
    "email": "string (required)",
    "first_name": "string",
    "last_name": "string",
    "is_active": "boolean",
    "phone": "string"
  }]
}

```

### `PATCH /api/v2/system/user/{id}`

### `DELETE /api/v2/system/user/{id}`

---

## App Management

Apps hold API keys. Each app gets its own `api_key` used in `X-DreamFactory-API-Key`.

### `GET /api/v2/system/app` — List Apps

### `POST /api/v2/system/app` — Create App

**Request schema:**

```
{
  "resource": [{
    "name": "string (required)",
    "label": "string",
    "description": "string",
    "is_active": "boolean"
  }]
}

```

**Response includes `api_key`** — this is the value used in `X-DreamFactory-API-Key` for all requests.

### `PATCH /api/v2/system/app/{id}`

### `DELETE /api/v2/system/app/{id}`

---

## Service Management

Services are database connections, file storage, APIs, etc. Each gets a `name` (namespace) used in API paths like `/api/v2/{name}/_table/...`.

### `GET /api/v2/system/service` — List Services

### `POST /api/v2/system/service` — Create Service

**Request schema:**

```
{
  "resource": [{
    "name": "string (required) — becomes URL namespace, lowercase alphanumeric",
    "label": "string (required) — display name",
    "type": "string (required) — service type id, e.g. 'mysql', 'sqlite', 'aws_s3'",
    "description": "string",
    "is_active": "boolean",
    "config": "object — type-specific configuration"
  }]
}

```

**Get available service types:**

```
curl -s http://your-df-host/api/v2/system/service_type \
  -H "X-DreamFactory-API-Key: KEY" \
  -H "X-DreamFactory-Session-Token: TOKEN"

```

### `PATCH /api/v2/system/service/{id}`

### `DELETE /api/v2/system/service/{id}`

---

## Role Management

Roles control what services and operations a user or app can access (RBAC).

### `GET /api/v2/system/role` — List Roles

### `POST /api/v2/system/role` — Create Role

**Request schema:**

```
{
  "resource": [{
    "name": "string (required)",
    "description": "string",
    "is_active": "boolean"
  }]
}

```

### `PATCH /api/v2/system/role/{id}`

### `DELETE /api/v2/system/role/{id}`

---

## CORS Configuration

### `GET /api/v2/system/cors` — List CORS Rules

### `POST /api/v2/system/cors` — Create CORS Rule

### `PATCH /api/v2/system/cors/{id}`

### `DELETE /api/v2/system/cors/{id}`

---

## Other System Endpoints

Endpoint

Method

Description

`/api/v2/system/environment`

GET

System environment info (version, platform, etc.)

`/api/v2/system/event`

GET

List system events

`/api/v2/system/cache`

DELETE

Clear all cache

`/api/v2/system/cache/{service}`

DELETE

Clear cache for one service

`/api/v2/system/lookup`

GET/POST/PATCH/DELETE

Manage lookup keys (global variables)

`/api/v2/system/constant`

GET

Read-only system constants

`/api/v2/system/package`

GET/POST

Export/import configuration packages

`/api/v2/system/email_template`

GET/POST/PATCH/DELETE

Manage email templates

`/api/v2/system/custom`

GET/POST/PATCH/DELETE

Custom system settings

---

## Common Query Parameters (all list endpoints)

Parameter

Type

Description

`fields`

string

Comma-separated fields to return, `*` for all

`related`

string

Related resources to include

`ids`

string

Comma-separated IDs to retrieve

`filter`

string

SQL-like filter, e.g. `is_active=1`

`limit`

integer

Max records to return

`offset`

integer

Skip N records

`order`

string

Sort, e.g. `name ASC`

`include_count`

boolean

Include total count in meta

---

## Response Envelope

All list responses are wrapped:

```
{
  "resource": [ {...}, {...} ],
  "meta": { "count": 10 }
}

```

Single-record responses (by ID) return the object directly.

Retrieved from "[https://wiki.dreamfactory.com/index.php?title=System_Api&oldid=967](https://wiki.dreamfactory.com/index.php?title=System_Api&oldid=967)"
		[Categories](/Special:Categories): - [System Api](/Category:System_Api)
- [Admin](/index.php?title=Category:Admin&action=edit&redlink=1)
- [User Management](/Category:User_Management)
- [API](/Category:API)