---
title: "System API | DreamFactory Docs"
source: "https://docs.dreamfactory.com/api-reference/system-api"
canonical_url: "https://docs.dreamfactory.com/api-reference/system-api"
converted_at: "2026-04-05T13:52:01.920Z"
format: "markdown"
converted_by: "html-to-md-ai"
---
>
> 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](/api-reference/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-reference/api-discovery).
>
>
>

---

## Session Management[​](#session-management)

### `POST /api/v2/system/admin/session` — Login[​](#post-apiv2systemadminsession--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[​](#get-apiv2systemadminsession--refresh--check)

Refreshes the current session token. Returns current user info.

### `PUT /api/v2/system/admin/session` — Refresh via token param[​](#put-apiv2systemadminsession--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[​](#delete-apiv2systemadminsession--logout)

Destroys the current session.

---

## Admin Management[​](#admin-management)

### `GET /api/v2/system/admin`[​](#get-apiv2systemadmin)

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`[​](#post-apiv2systemadmin)

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[​](#patch-apiv2systemadminid--update-admin)

### `DELETE /api/v2/system/admin/{id}` — Delete Admin[​](#delete-apiv2systemadminid--delete-admin)

### `POST /api/v2/system/admin/password` — Change Password[​](#post-apiv2systemadminpassword--change-password)

### `GET/POST /api/v2/system/admin/profile` — Get/Update Profile[​](#getpost-apiv2systemadminprofile--getupdate-profile)

---

## User Management[​](#user-management)

Non-admin users. Same pattern as admin endpoints.

### `GET /api/v2/system/user`[​](#get-apiv2systemuser)

### `POST /api/v2/system/user`[​](#post-apiv2systemuser)

**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}`[​](#patch-apiv2systemuserid)

### `DELETE /api/v2/system/user/{id}`[​](#delete-apiv2systemuserid)

---

## App Management[​](#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[​](#get-apiv2systemapp--list-apps)

### `POST /api/v2/system/app` — Create App[​](#post-apiv2systemapp--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}`[​](#patch-apiv2systemappid)

### `DELETE /api/v2/system/app/{id}`[​](#delete-apiv2systemappid)

---

## Service Management[​](#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[​](#get-apiv2systemservice--list-services)

### `POST /api/v2/system/service` — Create Service[​](#post-apiv2systemservice--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}`[​](#patch-apiv2systemserviceid)

### `DELETE /api/v2/system/service/{id}`[​](#delete-apiv2systemserviceid)

---

## Role Management[​](#role-management)

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

### `GET /api/v2/system/role` — List Roles[​](#get-apiv2systemrole--list-roles)

### `POST /api/v2/system/role` — Create Role[​](#post-apiv2systemrole--create-role)

**Request schema:**

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

### `PATCH /api/v2/system/role/{id}`[​](#patch-apiv2systemroleid)

### `DELETE /api/v2/system/role/{id}`[​](#delete-apiv2systemroleid)

---

## CORS Configuration[​](#cors-configuration)

### `GET /api/v2/system/cors` — List CORS Rules[​](#get-apiv2systemcors--list-cors-rules)

### `POST /api/v2/system/cors` — Create CORS Rule[​](#post-apiv2systemcors--create-cors-rule)

### `PATCH /api/v2/system/cors/{id}`[​](#patch-apiv2systemcorsid)

### `DELETE /api/v2/system/cors/{id}`[​](#delete-apiv2systemcorsid)

---

## Other System Endpoints[​](#other-system-endpoints)

EndpointMethodDescription`/api/v2/system/environment`GETSystem environment info (version, platform, etc.)`/api/v2/system/event`GETList system events`/api/v2/system/cache`DELETEClear all cache`/api/v2/system/cache/{service}`DELETEClear cache for one service`/api/v2/system/lookup`GET/POST/PATCH/DELETEManage lookup keys (global variables)`/api/v2/system/constant`GETRead-only system constants`/api/v2/system/package`GET/POSTExport/import configuration packages`/api/v2/system/email_template`GET/POST/PATCH/DELETEManage email templates`/api/v2/system/custom`GET/POST/PATCH/DELETECustom system settings

---

## Common Query Parameters (all list endpoints)[​](#common-query-parameters-all-list-endpoints)

ParameterTypeDescription`fields`stringComma-separated fields to return, `*` for all`related`stringRelated resources to include`ids`stringComma-separated IDs to retrieve`filter`stringSQL-like filter, e.g. `is_active=1``limit`integerMax records to return`offset`integerSkip N records`order`stringSort, e.g. `name ASC``include_count`booleanInclude total count in meta

---

## Response Envelope[​](#response-envelope)

All list responses are wrapped:

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

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