EN SDK Control Plane

Managing the Editor control plane from Python

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

Control-plane clients use /__forge/editor/v1, separately from application CRUD. The server must enable that surface, and network/HTTPS/Host policies and user roles must permit access.

Login, read and revision-aware save

import json
from getpass import getpass
from json_api_forge import EditorControlPlaneClient

with EditorControlPlaneClient("https://forge-admin.example.com") as control:
    control.login("worker.name", getpass("Password: "))
    print(control.projects().data)
    old = control.document("WikiDemo", "app.json")
    content = json.loads(old.data["content"])
    content["version"] = "1.0.1"
    saved = control.save_document(
        "WikiDemo", "app.json",
        json.dumps(content, ensure_ascii=False, indent=2) + "\n",
        expected_sha256=old.data["sha256"],
    )
    print(saved.data)
    control.logout()

WikiDemo is the project directory name returned by the control plane, not the application helper's wiki-demo slug. If someone has changed the document, saving with its old SHA returns 409. Use expected_sha256="new" only for a new document, not as a force-overwrite mechanism.

Setup and sessions

setup_status, setup_founder, register, login and logout cover account lifecycle. The founder setup token is for the first account. Invitations use exact-format, single-use, expiring tokens. Disable server setup after completion.

Sessions are held in memory. The access token is removed from the returned authentication payload after adoption. has_session, set_session_token and clear_session manage local session state. logout attempts server-side invalidation and clears memory; close/aclose should be treated as local session/transport cleanup, not a replacement for server logout. An authenticated request returning 401 clears the session.

Method families

Area	Example methods
Profile/access	capabilities, profile, update_profile
Projects/documents	projects, create_project, documents, document, save_document, validate_project
Roles/members	roles, create_role, update_role, members, update_member, create_invitation
Collaboration	areas, create_area, messages, post_message, notes, create_note
Database browsing	database_catalog, database_rows
Files	attachments, upload_attachment, download_attachment
Calls/audit	start_call, call_ticket, call_client_url, audit

The existence of a UI control or SDK method does not grant permission; the server checks current scopes. update_member replaces membership state, so read existing relationships before treating it as a partial append.

Attachments

Upload takes a bounded snapshot of a regular, non-symlink file and checks file identity. Download writes a private temporary file, fsyncs and atomically replaces the destination. Be aware that an existing destination can be replaced. Large attachments must fit both client and server limits.

Audio/video

start_call and call_ticket prepare signaling/join access. The SDK is not a Python WebRTC audio/video capture engine. call_client_url puts the ticket in the URL fragment; the browser presents it through a WebSocket subprotocol. Do not move it to a query parameter.

Async equivalents use await and async with. All signatures and request models are in the reference index.

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• python-library/json_api_forge/control_plane.py
• main/framework/editor_api.py
• python-library/contract-tests/test_against_main.py

---

English home · All English pages · Version maintenance