# Flowg8 API reference

Public docs. All IDs are synthetic; credentials are environment placeholders. Do not assume undocumented features exist.

# Flowg8 · Integrations

Reusable outbound connections and designer-managed email trigger addresses.

Security policy: only assigned authenticated approvers/reviewers may access private process content. Guest approvals, external document references and outbound sharedFields are disabled. Use private uploads and static outbound notifications. New Live executions retain evidence for three calendar months on Free or twelve on paid plans after final completion; open Live executions do not expire by age. Existing longer deadlines remain protected. Sandbox remains at 30 days from creation.

## GET /v1/integrations

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/integrations" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

Source: /docs/integrations
Full schemas: /docs/openapi.json


---

# Flowg8 · Create integration

Create a named outbound connection. Email triggers are managed through flow drafts.

kind=email requires config.recipientDomains. teams requires a Microsoft Teams Workflows HTTPS URL; http accepts HTTPS and optional authorization. Creating email_inbound separately returns EMAIL_TRIGGER_DESIGNER_REQUIRED. Create or save a flow draft with start.trigger={kind:email,integrationId:null}; an address is allocated atomically, after verifying an organization sender domain with TXT. No customer gateway secret is needed.

## POST /v1/integrations

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- name (string, required): min length 1 · max length 80
- kind (string, required): email | teams | http | email_inbound
- active (boolean, optional): default true
- config (object, required): 

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/integrations" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-create-integration-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "name": "Purchasing HTTP",
  "kind": "http",
  "active": true,
  "config": {
    "url": "https://example.com/flow-events"
  }
}'
```

Source: /docs/create-integration
Full schemas: /docs/openapi.json


---

# Flowg8 · Update integration

Update a connection using its current revision; kind is immutable.

Omitted URL/authorization retain stored values; authorization:"" clears the header. Changing settings increments revision. Already queued actions stop with INTEGRATION_CHANGED until an authorized explicit retry accepts the new revision. Disabling stops future delivery attempts. The updating administrator becomes the responsible owner for inbound processing.

## PUT /v1/integrations/{integrationId}

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- name (string, required): min length 1 · max length 80
- kind (string, required): email | teams | http | email_inbound
- active (boolean, optional): default true
- config (object, required): 
- revision (integer, required): min 1 · max 9007199254740991

## Request example (replace example IDs)

```sh
curl -X PUT "https://api.flowg8.io/v1/integrations/10000000-0000-4000-8000-000000000013" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-update-integration-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "name": "Purchasing HTTP",
  "kind": "http",
  "active": false,
  "revision": 1,
  "config": {}
}'
```

Source: /docs/update-integration
Full schemas: /docs/openapi.json


---

# Flowg8 · Company domains

List TXT ownership challenges. Sandbox inherits Live domain ownership.



## GET /v1/organization/domains

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Active workspace membership required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/organization/domains" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

Source: /docs/domains
Full schemas: /docs/openapi.json


---

# Flowg8 · Add company domain

Generate a TXT challenge without changing the customer DNS.

Administrator user token required. Add the returned txtName/txtValue at the domain DNS provider. Ownership does not configure email delivery, DKIM or MX and does not verify webhook targets owned by third-party SaaS providers.

## POST /v1/organization/domains

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- domain (string, required): 

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/organization/domains" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-add-domain-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "domain": "example.com"
}'
```

Source: /docs/add-domain
Full schemas: /docs/openapi.json


---

# Flowg8 · Verify domain TXT

Resolve the challenge and reserve the verified domain for the organization.

409 DOMAIN_NOT_VERIFIED means the expected TXT is not visible yet. 409 DOMAIN_IN_USE means another organization already owns the verified domain. Retrying after DNS propagation needs a new Idempotency-Key.

## POST /v1/organization/domains/{domainId}/verify

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/organization/domains/10000000-0000-4000-8000-000000000014/verify" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-verify-domain-001" \
  -H "content-type: application/json" \
  --data-raw '{}'
```

Source: /docs/verify-domain
Full schemas: /docs/openapi.json


---

# Flowg8 · Action deliveries

Read durable delivery state for email, Teams and HTTP steps.

Statuses pending, delivered, failed, continued, test, cancelled; attempts and safe error code only. The flow waits for delivery. Success means the destination accepted the request, not that a human read it. At most five automatic attempts with backoff; delivery is at least once. Sandbox records test actions and never calls destinations.

Only active signed-in members of an assigned approval or acknowledgment group with a pending or completed task can read private content. Blocked/cancelled tasks, unassigned administrators, requesters and all API keys grant no content access. Current membership is checked on every request and replay. Lists and cursors obey the same boundary. New Live executions retain evidence for three calendar months on Free or twelve on paid plans after final completion; open Live executions do not expire by age. Existing longer deadlines remain protected. Sandbox content expires after 30 days from creation.

## GET /v1/flow-runs/{runId}/actions

Authentication: restricted integration key (scope: runs:read) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Matching approval group required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/flow-runs/10000000-0000-4000-8000-000000000004/actions" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

Source: /docs/run-actions
Full schemas: /docs/openapi.json


---

# Flowg8 · Retry failed action

Explicitly retry a failed step while its run is waiting.

Requester who owns the run or workspace manager required. The current active connection revision is accepted on retry. HTTP receivers should deduplicate by the stable action id in Idempotency-Key and payload.id. Email/Teams may duplicate after ambiguous network failures.

## POST /v1/flow-runs/{runId}/actions/{actionId}/retry

Authentication: restricted integration key (scope: runs:start) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Requester role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/flow-runs/10000000-0000-4000-8000-000000000004/actions/10000000-0000-4000-8000-000000000015/retry" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-retry-action-001" \
  -H "content-type: application/json" \
  --data-raw '{}'
```

Source: /docs/retry-action
Full schemas: /docs/openapi.json


---

# Flowg8 · Email triggers

Verify sender domains with TXT, insert an email trigger and forward email to its generated address.

Verify a domain in Organization → Integrations & Domains. Only verified exact ORIGINAL sender domains are accepted, including forwarded emails. An original gmx.de sender stays blocked if only prange.io is verified. Sender authentication, spam and malware checks still apply. The forwarding mailbox domain does not grant access.

The designer disables email triggers until domain configuration is ready. Inserting one saves the draft and reserves a unique address bound to organization, flow and node. Copy it from the node settings and publish the flow before sending email. No separate inbox integration, signing key or customer MX changes are required.

API: POST /v1/designer-flows or save a draft with start.trigger={kind:email,integrationId:null}. The returned draft contains its allocated integrationId; GET /v1/integrations returns the matching destination and verifiedSenderDomains. Ordinary saves retain the address. Removing or replacing the email start on a draft/version write revokes the old address and routing immediately; old addresses cannot be restored by undo or copied to a different flow. Re-inserting creates a fresh address. Running processes and historical versions remain immutable. UI removal requires confirmation.

Only the platform gateway calls /v1/inbound-email/{integrationId}/context|upload|confirm|receive with the server-only platform HMAC secret. Full subject/message are stored as private source context, never copied into generic run.data. A default optional emailAttachments document field is created; set documents[].required=true for mandatory attachments. Attachments use private scanned S3 document uploads with the existing approver-only access. The central platform receiving domain retains its shared SES/MX infrastructure; nothing is provisioned per customer or trigger.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/access" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

Source: /docs/email-ingress
Full schemas: /docs/openapi.json


---

# Flowg8 · Edit a flow with AI

Describe an incremental change to the current schema v2 draft.

Administrator or Sandbox developer with a user access token required; integration keys are excluded. Pass the current definition and optional selection {nodeId,output:next|yes|no|rejectedNext|null}. A blank two-node flow anchors after the trigger. Select a branch for multi-output steps; ambiguous placement returns questions and definition:null. Enter submits in the designer; Shift+Enter adds a line. The search icon retains node finding.

Returns merged definition, summary, questions, assumptions, unresolvedGroups, model and changes {added,updated,removed,fields,documents,connections}. The API generates a suggestion without saving or executing it. Applying an email trigger change in the designer saves the draft to allocate or revoke its address. No publication or process start occurs. Preserve local geometry and reject a response if the draft changed while waiting. The designer retains existing positions, places only new nodes and supports undo of up to ten consecutive AI edits. Manual semantic changes disable the previous AI undo; manual movement survives undo.

Only design context and group names are sent to the EU-verified provider. Existing fixed guest emails are redacted; recipient settings cannot be AI-updated. No execution data, memberships, document bytes or URLs are loaded. Unknown groups remain unresolved. The existing AI draft budget applies; 3,000 prompt characters, 128 KiB body, at most 12 added/12 updated nodes and 40 connections per response, 40 total nodes. Invalid/cyclic changes are rejected atomically. No Idempotency-Key is needed; retries consume another AI reservation.

AI is disabled by default per organization and environment. An administrator must explicitly enable external AI processing under Organization → Privacy. Never include credentials or confidential personal information. Local keyword search remains available with smart=false.

## POST /v1/ai/flow-edits

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- prompt (string, required): min length 3 · max length 3000
- locale (string, optional): en | de · default "en"
- name (string, required): min length 1 · max length 120
- definition (object, required): 
- selection (object, optional): default null

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/ai/flow-edits" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-edit-flow-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "prompt": "Entscheidung mehr oder weniger als 500 Euro",
  "locale": "de",
  "name": "Synthetic flow",
  "definition": {
    "schemaVersion": 2,
    "fields": [],
    "nodes": [
      {
        "id": "start",
        "type": "start",
        "label": "Request received",
        "next": "end"
      },
      {
        "id": "end",
        "type": "end",
        "label": "Approved",
        "outcome": "approved"
      }
    ]
  },
  "selection": {
    "nodeId": "start",
    "output": "next"
  }
}'
```

## Response excerpt

```json
{
  "definition": null,
  "summary": "Choose a branch",
  "questions": [
    "Which branch should receive the step?"
  ],
  "assumptions": [],
  "unresolvedGroups": [],
  "model": "configured-model",
  "changes": {
    "added": 0,
    "updated": 0,
    "removed": 0,
    "fields": 0,
    "documents": 0,
    "connections": 0
  }
}
```

Source: /docs/edit-flow
Full schemas: /docs/openapi.json


---

# Flowg8 · Workflow building blocks

Use separate schema v2 node types for a decision, confirmed receipt or a non-blocking message.

Security policy: only assigned authenticated approvers/reviewers may access private process content. Guest approvals, external document references and outbound sharedFields are disabled. Use private uploads and static outbound notifications. New Live executions retain evidence for three calendar months on Free or twelve on paid plans after final completion; open Live executions do not expire by age. Existing longer deadlines remain protected. Sandbox remains at 30 days from creation.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/access" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "schemaVersion": 2,
  "fields": [],
  "nodes": [
    {
      "id": "start",
      "type": "start",
      "label": "Received",
      "next": "note"
    },
    {
      "id": "note",
      "type": "acknowledgment",
      "label": "Take note",
      "groupId": "10000000-0000-4000-8000-000000000009",
      "next": "notify"
    },
    {
      "id": "notify",
      "type": "notification",
      "label": "Recorded",
      "groupId": "10000000-0000-4000-8000-000000000009",
      "message": "The request has been recorded.",
      "next": "end"
    },
    {
      "id": "end",
      "type": "end",
      "label": "Completed",
      "outcome": "completed"
    }
  ]
}
```

Source: /docs/step-types
Full schemas: /docs/openapi.json


---

# Flowg8 · Personal notifications

Read notifications addressed to your signed-in user.

User token and active organization membership required. Only own entries are returned; administrator status grants no access to someone else’s inbox. Integration keys cannot use this endpoint. Supports cursor pagination (50 entries). Notification data includes id, runId, nodeId, title, message, flowName, referenceId, createdAt and emailStatus. It contains no attachment content or private URLs.

## GET /v1/notifications

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Active workspace membership required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/notifications" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "items": [],
  "nextCursor": null
}
```

Source: /docs/notifications
Full schemas: /docs/openapi.json


---

# Flowg8 · Documents at the trigger

Accept uploads and external links; only assigned approvers can open the documents.

Security policy: only assigned authenticated approvers/reviewers may access private process content. Guest approvals, external document references and outbound sharedFields are disabled. Use private uploads and static outbound notifications. New Live executions retain evidence for three calendar months on Free or twelve on paid plans after final completion; open Live executions do not expire by age. Existing longer deadlines remain protected. Sandbox remains at 30 days from creation.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/access" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

Source: /docs/documents
Full schemas: /docs/openapi.json


---

# Flowg8 · Reserve a document upload

Request a five-minute upload capability for one immutable file.

Requires runs:start or requester access and Idempotency-Key. Flow version must be published and document field/type/size configured. PUT the actual file bytes to upload.url, sending every upload.headers value exactly. Do not send your Flowg8 token to S3. Upload capability does not grant read access. SHA-256 is lowercase hexadecimal over the exact file bytes; S3 validates the signed checksum and a conditional write prevents overwrites. Retrying the same reservation may refresh its transient upload URL.

## POST /v1/documents/uploads

Authentication: restricted integration key (scope: runs:start) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Requester role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- flowVersionId (string, required): uuid
- fieldKey (string, required): 
- fileName (string, required): min length 1 · max length 180
- contentType (string, required): application/pdf | image/png | image/jpeg | application/vnd.openxmlformats-officedocument.wordprocessingml.document
- size (integer, required): min 1 · max 26214400
- sha256 (string, required): 

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/documents/uploads" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-document-upload-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "flowVersionId": "10000000-0000-4000-8000-000000000003",
  "fieldKey": "contract",
  "fileName": "contract.pdf",
  "contentType": "application/pdf",
  "size": 1234,
  "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}'
```

## Response excerpt

```json
{
  "document": {
    "id": "10000000-0000-4000-8000-000000000012",
    "status": "uploading"
  },
  "upload": {
    "url": "https://private-bucket.s3.eu-central-1.amazonaws.com/<temporary-upload-capability>",
    "headers": {
      "content-type": "application/pdf",
      "x-amz-checksum-sha256": "<base64 checksum>",
      "if-none-match": "*"
    },
    "expiresAt": "2026-10-18T12:05:00.000Z"
  }
}
```

Source: /docs/document-upload
Full schemas: /docs/openapi.json


---

# Flowg8 · Confirm document upload

Verify size, checksum, object version and a successful malware scan.

Only the same uploading identity can confirm. Requires runs:start or requester access and Idempotency-Key. 409 DOCUMENT_SCAN_PENDING: retry the same confirmation after a short delay. 422 DOCUMENT_SCAN_REJECTED: do not attach the file; choose another. Only a ready document can start a run. Failed checks never grant read access. The exact S3 version is pinned at confirmation.

## POST /v1/documents/{documentId}/confirm

Authentication: restricted integration key (scope: runs:start) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Requester role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/documents/10000000-0000-4000-8000-000000000012/confirm" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-document-confirm-001" \
  -H "content-type: application/json" \
  --data-raw '{}'
```

## Response excerpt

```json
{
  "id": "10000000-0000-4000-8000-000000000012",
  "status": "ready"
}
```

Source: /docs/document-confirm
Full schemas: /docs/openapi.json


---

# Flowg8 · Attach external document link

Disabled: authenticated accounts assigned to the active approval or reviewer group are required.

This compatibility endpoint denies content access and decisions. Existing guest links cannot authorize access. Assign an internal group and upload files to private storage instead.

## POST /v1/documents/links

Authentication: restricted integration key (scope: runs:start) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Requester role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- flowVersionId (string, required): uuid
- fieldKey (string, required): 
- fileName (string, required): min length 1 · max length 180
- url (string, required): uri · max length 2048
- version (string, required): min length 1 · max length 180
- contentType (string, required): application/pdf | image/png | image/jpeg | application/vnd.openxmlformats-officedocument.wordprocessingml.document

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/documents/links" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-document-link-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "flowVersionId": "10000000-0000-4000-8000-000000000003",
  "fieldKey": "contract",
  "fileName": "contract.pdf",
  "contentType": "application/pdf",
  "url": "https://documents.example.com/contracts/123/versions/1",
  "version": "1"
}'
```

## Response excerpt

```json
{
  "error": "PRIVATE_UPLOAD_REQUIRED"
}
```

Source: /docs/document-link
Full schemas: /docs/openapi.json


---

# Flowg8 · Read incoming email

Read the complete private message and attachment metadata as an assigned approver.

Returns sender, recipient, complete subject and plain text, textOrigin (plain or html), receivedAt, expiresAt and attachment metadata. Private no-store response. Assigned active approval group required; blocked/future tasks, administrators without assignment, requesters, service keys, other tenants and expired runs are denied. Message content is never copied to general run.data, history or webhook payloads. GET run/document APIs do not grant email access. SDK: getRunEmail(runId).

Only active signed-in members of an assigned approval or acknowledgment group with a pending or completed task can read private content. Blocked/cancelled tasks, unassigned administrators, requesters and all API keys grant no content access. Current membership is checked on every request and replay. Lists and cursors obey the same boundary. New Live executions retain evidence for three calendar months on Free or twelve on paid plans after final completion; open Live executions do not expire by age. Existing longer deadlines remain protected. Sandbox content expires after 30 days from creation.

## GET /v1/flow-runs/{runId}/email

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Matching approval group required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/flow-runs/10000000-0000-4000-8000-000000000004/email" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

Source: /docs/received-email
Full schemas: /docs/openapi.json


---

# Flowg8 · Read shared incoming email

Disabled: authenticated accounts assigned to the active approval or reviewer group are required.

This compatibility endpoint denies content access and decisions. Existing guest links cannot authorize access. Assign an internal group and upload files to private storage instead.

## POST /v1/external-approvals/email

Authentication: public account endpoint; no token required
Required user permissions: No account role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- token (string, required): 

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/external-approvals/email" \
  -H "idempotency-key: example-external-received-email-001" \
  -H "content-type: application/json" \
  --data-raw "{\"token\":\"<private-approval-token>\"}"
```

## Response excerpt

```json
{
  "error": "EXTERNAL_ACCOUNT_REQUIRED"
}
```

Source: /docs/external-received-email
Full schemas: /docs/openapi.json


---

# Flowg8 · List review documents

Read document metadata for an execution you may approve.

Assigned approver user tokens only; runs:read keys, administrators and requesters without a matching activated approval gate receive 403. No upload URLs, storage keys or external URLs in this response. Empty list means no available documents.

Only active signed-in members of an assigned approval or acknowledgment group with a pending or completed task can read private content. Blocked/cancelled tasks, unassigned administrators, requesters and all API keys grant no content access. Current membership is checked on every request and replay. Lists and cursors obey the same boundary. New Live executions retain evidence for three calendar months on Free or twelve on paid plans after final completion; open Live executions do not expire by age. Existing longer deadlines remain protected. Sandbox content expires after 30 days from creation.

## GET /v1/flow-runs/{runId}/documents

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Matching approval group required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/flow-runs/10000000-0000-4000-8000-000000000004/documents" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "items": []
}
```

Source: /docs/document-list
Full schemas: /docs/openapi.json


---

# Flowg8 · Open a review document

Stream the pinned document after a fresh approval permission check.

Assigned approver user tokens only. S3 source: binary response with Content-Type/Content-Disposition, no redirect or signed download URL. External source: JSON {kind:"external",url:"https://…"}; open with no referrer. Every access is private/no-store and audited by document ID. Downloaded bytes cannot be remotely revoked; keep them confidential.

Only active signed-in members of an assigned approval or acknowledgment group with a pending or completed task can read private content. Blocked/cancelled tasks, unassigned administrators, requesters and all API keys grant no content access. Current membership is checked on every request and replay. Lists and cursors obey the same boundary. New Live executions retain evidence for three calendar months on Free or twelve on paid plans after final completion; open Live executions do not expire by age. Existing longer deadlines remain protected. Sandbox content expires after 30 days from creation.

## GET /v1/flow-runs/{runId}/documents/{documentId}/content

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Matching approval group required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/flow-runs/10000000-0000-4000-8000-000000000004/documents/10000000-0000-4000-8000-000000000012/content" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

Source: /docs/document-content
Full schemas: /docs/openapi.json


---

# Flowg8 · External review documents

Disabled: authenticated accounts assigned to the active approval or reviewer group are required.

This compatibility endpoint denies content access and decisions. Existing guest links cannot authorize access. Assign an internal group and upload files to private storage instead.

## POST /v1/external-approvals/documents

Authentication: public account endpoint; no token required
Required user permissions: No account role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- token (string, required): 

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/external-approvals/documents" \
  -H "idempotency-key: example-external-document-list-001" \
  -H "content-type: application/json" \
  --data-raw "{\"token\":\"$FLOWG8_APPROVAL_TOKEN\"}"
```

## Response excerpt

```json
{
  "error": "EXTERNAL_ACCOUNT_REQUIRED"
}
```

Source: /docs/external-document-list
Full schemas: /docs/openapi.json


---

# Flowg8 · Open external review document

Disabled: authenticated accounts assigned to the active approval or reviewer group are required.

This compatibility endpoint denies content access and decisions. Existing guest links cannot authorize access. Assign an internal group and upload files to private storage instead.

## POST /v1/external-approvals/documents/{documentId}/content

Authentication: public account endpoint; no token required
Required user permissions: No account role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- token (string, required): 

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/external-approvals/documents/10000000-0000-4000-8000-000000000012/content" \
  -H "idempotency-key: example-external-document-content-001" \
  -H "content-type: application/json" \
  --data-raw "{\"token\":\"$FLOWG8_APPROVAL_TOKEN\"}"
```

## Response excerpt

```json
{
  "error": "EXTERNAL_ACCOUNT_REQUIRED"
}
```

Source: /docs/external-document-content
Full schemas: /docs/openapi.json


---

# Flowg8 · Business profile

Read the saved business details and Live activation status.

Administrator user tokens only. Manage the parent Live organization under Organization → Business details. Integration keys and Sandbox developer grants cannot read or change business details.

Publishing Live flows and starting Live runs require a complete business profile and explicit Live activation. Draft publication, definition-version publication and process starts return 409 ORGANIZATION_NOT_LIVE until then. Draft editing and Sandbox publication/starts remain available. Existing runs can still be read and decided.

## GET /v1/organization/business-profile

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator role required · Live only. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/organization/business-profile" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

Source: /docs/business-profile
Full schemas: /docs/openapi.json


---

# Flowg8 · Save business details

Save progress with revision protection; partial drafts are supported.

Use revision 0 for the first save, then the revision returned by the API. VAT ID and commercial-register references are optional. Required: legalName, addressLine1, postalCode, city, country (ISO 3166-1 alpha-2), contactName, contactEmail and businessUseConfirmed. Activated organizations must keep required data complete. Requires Idempotency-Key.

## PUT /v1/organization/business-profile

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator role required · Live only. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- revision (integer, required): min 0 · max 9007199254740991
- details (object, required): 

## Request example (replace example IDs)

```sh
curl -X PUT "https://api.flowg8.io/v1/organization/business-profile" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-save-business-profile-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "revision": 0,
  "details": {
    "legalName": "Example GmbH",
    "addressLine1": "Teststraße 1",
    "addressLine2": "",
    "postalCode": "10115",
    "city": "Berlin",
    "country": "DE",
    "contactName": "Alex Example",
    "contactEmail": "operations@example.test",
    "vatId": "",
    "registerNumber": "",
    "businessUseConfirmed": true
  }
}'
```

Source: /docs/save-business-profile
Full schemas: /docs/openapi.json


---

# Flowg8 · Activate Live workflows

Activate production starts after saving and reviewing complete business details.

Administrator-only explicit confirmation. Uses the current saved revision and Idempotency-Key. Incomplete details return 400; stale revisions return 409. This does not purchase a subscription or change process quotas. Configuration completeness is checked; no identity or tax-register verification is performed.

## POST /v1/organization/activate-live

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator role required · Live only. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- revision (integer, required): min 1 · max 9007199254740991
- confirm (boolean, required): true

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/organization/activate-live" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-activate-live-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "revision": 1,
  "confirm": true
}'
```

Source: /docs/activate-live
Full schemas: /docs/openapi.json


---

# Flowg8 · Workflow webhooks

Receive selected workflow lifecycle events at your signed HTTPS endpoint.

Manage destinations in Organization → Webhooks using an administrator user token (Sandbox developers may manage their Sandbox). Configuration and secrets are separate per environment. Sandbox destinations make real HTTPS requests to your test receiver. Integration API keys cannot manage webhook destinations.

Events: run.started, gate.activated, gate.approved, gate.rejected, acknowledgment.requested, acknowledgment.completed, notification.created, notification.delivered, notification.failed, run.approved, run.rejected, run.completed, run.expired. Each payload has id, type, apiVersion, createdAt, sequence, organizationId, environment and data.run/data.gate/data.notification/data.outcome. The run includes id, referenceId, flowId and flowVersionId. Request fields and comments are not embedded; fetch details using the run API.

Verify Flowg8-Signature: t=<Unix seconds>,v1=<HMAC-SHA256 hex> over timestamp + "." + the unchanged raw HTTP body, using your fg_whsec_ secret. The SDK exports verifyWebhookSignature(rawBody, header, secret), enforcing a five-minute timestamp tolerance. A retry uses a fresh signature timestamp but the same event ID and payload. Deduplicate by event.id, accept out-of-order events, return 2xx promptly and process asynchronously.

Delivery is at least once, with up to ten automatic attempts within 72 hours. HTTPS/public destinations on port 443 only; private addresses and redirects are rejected. Delivery history is retained for up to 30 days, bounded by Sandbox data retention. Pausing prevents new messages and pauses queued messages; changing URL cancels pending deliveries rather than redirecting old events.

## GET /v1/webhook-endpoints

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/webhook-endpoints" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "configured": true,
  "items": []
}
```

Source: /docs/webhooks
Full schemas: /docs/openapi.json


---

# Flowg8 · Create webhook destination

Select a public destination and lifecycle events; receive its signing secret.

Requires an Idempotency-Key. The signing secret is returned only on creation or rotation, including a safe replay of that exact command. Keep it on your server; it is not an API access token. No real message is sent until a subscribed workflow event occurs.

## POST /v1/webhook-endpoints

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- name (string, required): min length 1 · max length 80
- url (string, required): uri · max length 2048
- events (array, required): min items 1 · max items 20
- active (boolean, optional): default true

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/webhook-endpoints" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-create-webhook-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "name": "ERP approvals",
  "url": "https://api.example.com/webhooks/flowg8",
  "events": [
    "gate.activated",
    "gate.approved",
    "gate.rejected",
    "run.approved",
    "run.rejected"
  ],
  "active": true
}'
```

## Response excerpt

```json
{
  "endpoint": {
    "id": "10000000-0000-4000-8000-000000000008",
    "name": "ERP approvals"
  },
  "signingSecret": "fg_whsec_<private signing secret>"
}
```

Source: /docs/create-webhook
Full schemas: /docs/openapi.json


---

# Flowg8 · Edit webhook destination

Change the destination, event selection or enabled state with revision protection.



## PUT /v1/webhook-endpoints/{endpointId}

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- name (string, required): min length 1 · max length 80
- url (string, required): uri · max length 2048
- events (array, required): min items 1 · max items 20
- active (boolean, optional): default true
- revision (integer, required): min 1 · max 9007199254740991

## Request example (replace example IDs)

```sh
curl -X PUT "https://api.flowg8.io/v1/webhook-endpoints/endpointId" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-update-webhook-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "name": "ERP approvals",
  "url": "https://api.example.com/webhooks/flowg8",
  "events": [
    "run.approved",
    "run.rejected"
  ],
  "active": true,
  "revision": 1
}'
```

Source: /docs/update-webhook
Full schemas: /docs/openapi.json


---

# Flowg8 · Rotate signing secret

Generate a new secret; the old secret stops being used immediately.



## POST /v1/webhook-endpoints/{endpointId}/rotate-secret

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- revision (integer, required): min 1 · max 9007199254740991

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/webhook-endpoints/endpointId/rotate-secret" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-rotate-webhook-secret-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "revision": 1
}'
```

Source: /docs/rotate-webhook-secret
Full schemas: /docs/openapi.json


---

# Flowg8 · Webhook delivery history

Inspect the latest 50 deliveries, attempts and HTTP status codes.



## GET /v1/webhook-endpoints/{endpointId}/deliveries

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/webhook-endpoints/endpointId/deliveries" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "items": []
}
```

Source: /docs/webhook-deliveries
Full schemas: /docs/openapi.json


---

# Flowg8 · Retry a failed delivery

Queue a failed message again within its original retry window, keeping its event ID.



## POST /v1/webhook-deliveries/{deliveryId}/retry

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/webhook-deliveries/deliveryId/retry" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-retry-webhook-delivery-001" \
  -H "content-type: application/json" \
  --data-raw '{}'
```

Source: /docs/retry-webhook-delivery
Full schemas: /docs/openapi.json


---

# Flowg8 · Review an external approval

Disabled: authenticated accounts assigned to the active approval or reviewer group are required.

This compatibility endpoint denies content access and decisions. Existing guest links cannot authorize access. Assign an internal group and upload files to private storage instead.

## POST /v1/external-approvals/resolve

Authentication: private approval capability in request body; no account token
Required user permissions: No account role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- token (string, required): 

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/external-approvals/resolve" \
  -H "content-type: application/json" \
  --data-raw "{\"token\":\"$FLOWG8_APPROVAL_TOKEN\"}"
```

## Response excerpt

```json
{
  "error": "EXTERNAL_ACCOUNT_REQUIRED"
}
```

Source: /docs/external-resolve
Full schemas: /docs/openapi.json


---

# Flowg8 · Record an external decision

Disabled: authenticated accounts assigned to the active approval or reviewer group are required.

This compatibility endpoint denies content access and decisions. Existing guest links cannot authorize access. Assign an internal group and upload files to private storage instead.

## POST /v1/external-approvals/decisions

Authentication: private approval capability in request body; no account token
Required user permissions: No account role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- token (string, required): 
- outcome (string, required): approved | rejected
- comment (string, optional): max length 2000 · default ""

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/external-approvals/decisions" \
  -H "idempotency-key: example-external-decide-001" \
  -H "content-type: application/json" \
  --data-raw "{\"token\":\"$FLOWG8_APPROVAL_TOKEN\",\"outcome\":\"approved\",\"comment\":\"Reviewed.\"}"
```

## Response excerpt

```json
{
  "error": "EXTERNAL_ACCOUNT_REQUIRED"
}
```

Source: /docs/external-decide
Full schemas: /docs/openapi.json


---

# Flowg8 · External delivery status

Disabled: authenticated accounts assigned to the active approval or reviewer group are required.

This compatibility endpoint denies content access and decisions. Existing guest links cannot authorize access. Assign an internal group and upload files to private storage instead.

## GET /v1/flow-runs/{runId}/external-approvals

Authentication: restricted integration key (scope: runs:read) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Matching approval group required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/flow-runs/10000000-0000-4000-8000-000000000004/external-approvals" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "error": "EXTERNAL_ACCOUNT_REQUIRED"
}
```

Source: /docs/external-status
Full schemas: /docs/openapi.json


---

# Flowg8 · Send a new approval link

Disabled: authenticated accounts assigned to the active approval or reviewer group are required.

This compatibility endpoint denies content access and decisions. Existing guest links cannot authorize access. Assign an internal group and upload files to private storage instead.

## POST /v1/gate-tasks/{taskId}/external-approval/resend

Authentication: restricted integration key (scope: flows:write) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/gate-tasks/10000000-0000-4000-8000-000000000005/external-approval/resend" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-external-resend-001" \
  -H "content-type: application/json" \
  --data-raw '{}'
```

## Response excerpt

```json
{
  "error": "EXTERNAL_ACCOUNT_REQUIRED"
}
```

Source: /docs/external-resend
Full schemas: /docs/openapi.json


---

# Flowg8 · Sandbox test mailbox

Disabled: authenticated accounts assigned to the active approval or reviewer group are required.

This compatibility endpoint denies content access and decisions. Existing guest links cannot authorize access. Assign an internal group and upload files to private storage instead.

## GET /v1/sandbox/mailbox

Authentication: restricted integration key (scope: flows:write) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/sandbox/mailbox" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "error": "EXTERNAL_ACCOUNT_REQUIRED"
}
```

Source: /docs/sandbox-mailbox
Full schemas: /docs/openapi.json


---

# Flowg8 · Postman collection

Import the Flowg8 API and separate Live/Sandbox environments into Postman.

Download the collection and one environment using the links above. In Postman choose Import, select both JSON files, then select Flowg8 · Live or Flowg8 · Sandbox. Set baseUrl if needed; enter email and password locally. No personal access token, password or API key is included in these downloads.

Send Get an access token, then Your organization. Tokens and IDs are saved automatically in the selected environment. In Sandbox also send Sandbox environments to select the isolated workspace. Complete sign-in handles temporary-password or MFA challenges. Refresh an access token renews credentials and keeps an existing refresh token when no replacement is returned.

Send the individual requests needed for your integration. Human-only operations require the user token; compatible operations prefer FLOWG8_API_KEY when you supply one. Invitations require a Live administrator token or an explicitly scoped service key. Create/read/save/publish flow responses update flowId, draftRevision and flowVersionId; process responses update runId and the pending taskId. Edit runData to match your published fields. Before retrying an uncertain mutation, copy LAST_IDEMPOTENCY_KEY into IDEMPOTENCY_KEY and keep identical input. Clear it for a new operation. Filled environments contain secrets: keep values local and do not share them.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/access" \

```

Source: /docs/postman
Full schemas: /docs/openapi.json


---

# Flowg8 · Get an access token

Sign in through the API without opening the web application.

Send your Flowg8 email and password privately over HTTPS. No AWS account, client ID, client secret, API key or prior browser session is required. This is the Flowg8 JSON sign-in API, not an OAuth password-grant endpoint. Never paste passwords or returned tokens into LLM prompts, logs or source control.

When status=authenticated, use accessToken as FLOWG8_ACCESS_TOKEN in Authorization: Bearer. expiresAt and expiresIn describe its lifetime. Keep refreshToken on your backend for renewal; tokens grant only the authenticated user’s current organization permissions. Resolve your organization with POST /v1/workspace {}, then send its ID in X-Organization-Id. A Live administrator can invite users including admins; a users:invite service key can invite ordinary members only.

A temporary password or MFA returns status=challenge_required with challenge and a short-lived opaque challengeToken. Complete POST /v1/auth/challenge before any access token is issued. Invalid credentials return 401, required email verification/password recovery 409, throttling 429. Per-instance protection allows 20 token/challenge requests per IP per minute; do not retry login in a tight loop.

Workspace access requires an enrolled authenticator. Complete /security in the browser first. Every API request validates the token online and refreshes group membership. Sign-out revokes all current Cognito sessions. API sign-in may return a standard MFA challenge.

## POST /v1/auth/token

Authentication: public account endpoint; no token required
Required user permissions: No account role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- grantType (string, required): password
- email (string, required): email · max length 254
- password (string, required): min length 1 · max length 256

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/auth/token" \
  -H "content-type: application/json" \
  --data-raw '{
  "grantType": "password",
  "email": "alex@example.com",
  "password": "YOUR_PASSWORD"
}'
```

## Response excerpt

```json
{
  "status": "authenticated",
  "tokenType": "Bearer",
  "accessToken": "YOUR_FLOWG8_ACCESS_TOKEN",
  "expiresIn": 3600,
  "expiresAt": "2026-10-17T12:00:00.000Z",
  "refreshToken": "YOUR_REFRESH_TOKEN"
}
```

Source: /docs/obtain-token
Full schemas: /docs/openapi.json


---

# Flowg8 · Refresh an access token

Renew access without sending your password again.

Use the refresh token returned by sign-in. No bearer token or organization header is required. Store any returned replacement refreshToken atomically; if none is returned, keep the previous one. Access-token expiry never extends organization membership or administrator rights. If renewal fails with 401, authenticate again. Flowg8 does not store these tokens.

## POST /v1/auth/token

Authentication: public account endpoint; no token required
Required user permissions: No account role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- grantType (string, required): refresh_token
- refreshToken (string, required): min length 1 · max length 4096

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/auth/token" \
  -H "content-type: application/json" \
  --data-raw '{
  "grantType": "refresh_token",
  "refreshToken": "YOUR_REFRESH_TOKEN"
}'
```

## Response excerpt

```json
{
  "status": "authenticated",
  "tokenType": "Bearer",
  "accessToken": "YOUR_FLOWG8_ACCESS_TOKEN",
  "expiresIn": 3600,
  "expiresAt": "2026-10-17T12:00:00.000Z"
}
```

Source: /docs/refresh-token
Full schemas: /docs/openapi.json


---

# Flowg8 · Complete sign-in

Complete the first-login password change or an MFA challenge through the API.

Copy challengeToken from the last challenge_required response; it expires after 180 seconds. For NEW_PASSWORD_REQUIRED send newPassword (14+ characters, mixed case, number and symbol, no spaces). For SMS_MFA, SOFTWARE_TOKEN_MFA or EMAIL_OTP send code instead. Never send both. Continue if a further challenge is returned. No token is issued before all mandatory challenges succeed.

## POST /v1/auth/challenge

Authentication: public account endpoint; no token required
Required user permissions: No account role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- challengeToken (string, required): min length 1 · max length 12000
- newPassword (string, optional): min length 1 · max length 256
- code (string, optional): 

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/auth/challenge" \
  -H "content-type: application/json" \
  --data-raw '{
  "challengeToken": "YOUR_CHALLENGE_TOKEN",
  "newPassword": "YOUR_NEW_PASSWORD"
}'
```

## Response excerpt

```json
{
  "status": "authenticated",
  "tokenType": "Bearer",
  "accessToken": "YOUR_FLOWG8_ACCESS_TOKEN",
  "expiresIn": 3600,
  "expiresAt": "2026-10-17T12:00:00.000Z"
}
```

Source: /docs/auth-challenge
Full schemas: /docs/openapi.json


---

# Flowg8 · Create an account

Register a Flowg8 account with your name, email and password.

Registration is closed in production before launch. Registration, confirmation and code resend return 403 REGISTRATION_DISABLED without creating accounts or sending mail.

Public account endpoint. Replace YOUR_NEW_PASSWORD privately with a password of at least 14 characters, uppercase/lowercase, a number and a symbol, without spaces. Never put passwords in logs or LLM prompts. No organization exists until email verification succeeds.

## POST /v1/registration

Authentication: public account endpoint; no token required
Required user permissions: No account role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- locale (string, optional): max length 35
- email (string, required): email · max length 128
- displayName (string, required): min length 1 · max length 120
- password (string, required): min length 14 · max length 256

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/registration" \
  -H "content-type: application/json" \
  --data-raw '{
  "displayName": "Alex Example",
  "email": "alex@example.com",
  "password": "YOUR_NEW_PASSWORD"
}'
```

## Response excerpt

```json
{
  "confirmed": false
}
```

Source: /docs/register-account
Full schemas: /docs/openapi.json


---

# Flowg8 · Verify email

Verify the emailed code and initialize your organization automatically.

Registration is closed in production before launch. Registration, confirmation and code resend return 403 REGISTRATION_DISABLED without creating accounts or sending mail.

After a valid code, Flowg8 creates one Live organization, one Sandbox and the founder profile in both environments. The founder receives administrator and requester access. Sign in to retrieve organization IDs through POST /v1/workspace. A failed initialization is repaired on the next authenticated login. POST /v1/registration/resend accepts {email} to request another code.

## POST /v1/registration/confirm

Authentication: public account endpoint; no token required
Required user permissions: No account role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- email (string, required): email · max length 128
- code (string, required): 

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/registration/confirm" \
  -H "content-type: application/json" \
  --data-raw '{
  "email": "alex@example.com",
  "code": "123456"
}'
```

## Response excerpt

```json
{
  "confirmed": true
}
```

Source: /docs/confirm-account
Full schemas: /docs/openapi.json


---

# Flowg8 · Your organization

Resolve your organization after Flowg8 sign-in.

Use FLOWG8_ACCESS_TOKEN issued by your normal Flowg8 sign-in. Flowg8 manages authentication; no separate identity-provider setup is required. Invitations are matched to the verified user identity and join the existing organization, without creating a personal one. Empty requests reuse the active organization. To switch, send {organizationId} for an active membership returned by GET /v1/workspaces. Removing membership prevents access.

## POST /v1/workspace

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required user permissions: Flowg8 sign-in required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/workspace" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "content-type: application/json" \
  --data-raw '{}'
```

## Response excerpt

```json
{
  "organization": {
    "id": "10000000-0000-4000-8000-000000000001",
    "name": "My workspace"
  },
  "roles": [
    "admin",
    "requester"
  ]
}
```

Source: /docs/workspace
Full schemas: /docs/openapi.json


---

# Flowg8 · Your organizations

List active organization memberships for the signed-in person.



## GET /v1/workspaces

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required user permissions: Flowg8 sign-in required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/workspaces" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN"
```

## Response excerpt

```json
{
  "items": [
    {
      "id": "10000000-0000-4000-8000-000000000001",
      "name": "Example organization"
    }
  ]
}
```

Source: /docs/workspaces
Full schemas: /docs/openapi.json


---

# Flowg8 · Invite a user

Invite a person with a login, organization role and optional approval groups.

Use a Live administrator token, a Sandbox administrator/developer token, or a service-account key with users:invite. Service keys may invite requester members with no approvalGroupIds; admin invitations and approval-group grants require the administrator user token. In Sandbox, the same request creates a simulated invitation (delivery=simulated), with no email or real account. POST /v1/sandbox/invitations/{id}/accept simulates first sign-in and links its personId to a Sandbox-only identity. A new Flowg8 account receives an email with a temporary password and must set a personal password on first sign-in. Existing eligible accounts keep their password and accept by signing in again; ask them directly to sign in. Flowg8 returns no passwords.

The API checks active workspace access and either administrator user rights or a service-account users:invite scope before reserving or retrying an invitation. role describes the invited person, not the caller: role=admin cannot grant permission to send the request. Missing/invalid access tokens return 401; non-admin user tokens, inactive or foreign memberships, keys without users:invite and privileged service-key invitations return 403. Invitation validity: 7 days. Membership and direct approval-group grants activate only for the matching authenticated subject. Requester is the default role; admin must be explicit. Directory profiles remain independently editable. Reuse the same Idempotency-Key and input after uncertain results.

Service accounts require users:invite and can list/retry only invitations created by that same service account, including after key rotation. They cannot create admin invitations, assign approval groups or delegate credentials. Live invitations create real accounts; Sandbox invitations simulate provisioning and acceptance without sending emails.

## POST /v1/organization/invitations

Authentication: restricted integration key (scope: users:invite) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- locale (string, optional): max length 35
- displayName (string, required): min length 1 · max length 120
- email (string, required): email · max length 128
- role (string, optional): requester | admin · default "requester"
- approvalGroupIds (array, optional): max items 50 · default []

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/organization/invitations" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-invite-user-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "displayName": "Alex Example",
  "email": "alex@example.com",
  "role": "requester",
  "approvalGroupIds": []
}'
```

## Response excerpt

```json
{
  "status": "invited",
  "delivery": "temporary_password"
}
```

Source: /docs/invite-user
Full schemas: /docs/openapi.json


---

# Flowg8 · Simulate invitation acceptance

Link the invited test person to a simulated Sandbox account.

Sandbox only. Requires a Sandbox administrator/developer session, or the same service account with users:invite that created the invitation. Repeating acceptance returns the same result. No password, access token or real account is issued. The linked identity belongs only to this Sandbox.

## POST /v1/sandbox/invitations/{invitationId}/accept

Authentication: restricted integration key (scope: users:invite) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required · Sandbox only. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/sandbox/invitations/invitationId/accept" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "content-type: application/json" \
  --data-raw '{}'
```

## Response excerpt

```json
{
  "status": "accepted",
  "delivery": "simulated"
}
```

Source: /docs/accept-sandbox-invitation
Full schemas: /docs/openapi.json


---

# Flowg8 · Validate user import

Validate up to 100 people without creating profiles, accounts or emails.

Use an administrator session in Live or an administrator/developer session in Sandbox. Integration access requires a service-account key with BOTH organization:write and users:invite. Keys can access/retry only imports owned by the same service account. Access is rechecked during background processing.

## POST /v1/organization/user-imports/validate

Authentication: restricted integration key (scope: users:invite) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- people (array, required): min items 1 · max items 100

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/organization/user-imports/validate" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "content-type: application/json" \
  --data-raw '{
  "people": [
    {
      "ref": "ceo",
      "externalId": "employee-1",
      "displayName": "Alex Example",
      "email": "alex@example.com",
      "jobTitle": "CEO",
      "managerRef": null
    },
    {
      "ref": "lead",
      "externalId": "employee-2",
      "displayName": "Kim Example",
      "email": "kim@example.com",
      "jobTitle": "Team Lead",
      "managerRef": "ceo"
    }
  ]
}'
```

## Response excerpt

```json
{
  "valid": true,
  "issues": [],
  "summary": {
    "people": 2,
    "created": 2,
    "updated": 0,
    "alreadyLinked": 0,
    "invitations": 2
  }
}
```

Source: /docs/validate-user-import
Full schemas: /docs/openapi.json


---

# Flowg8 · Start user import

Atomically save the validated directory and queue invitations.

Returns HTTP 202 with a job ID and person IDs. One active import per organization; reuse the same Idempotency-Key after an uncertain response. Required fields: displayName, email and externalId or ref. managerRef resolves within this import; managerExternalId can also resolve an existing active person in the same organization. Order is irrelevant. personId may explicitly select an existing profile. Omitting jobTitle, unitId or manager fields preserves existing values. Explicit null clears a unit/manager. No administrators or approval grants are imported.

Use an administrator session in Live or an administrator/developer session in Sandbox. Integration access requires a service-account key with BOTH organization:write and users:invite. Keys can access/retry only imports owned by the same service account. Access is rechecked during background processing.

## POST /v1/organization/user-imports

Authentication: restricted integration key (scope: users:invite) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- people (array, required): min items 1 · max items 100

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/organization/user-imports" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-create-user-import-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "people": [
    {
      "ref": "ceo",
      "externalId": "employee-1",
      "displayName": "Alex Example",
      "email": "alex@example.com",
      "jobTitle": "CEO",
      "managerRef": null
    },
    {
      "ref": "lead",
      "externalId": "employee-2",
      "displayName": "Kim Example",
      "email": "kim@example.com",
      "jobTitle": "Team Lead",
      "managerRef": "ceo"
    }
  ]
}'
```

## Response excerpt

```json
{
  "id": "import-uuid",
  "status": "queued",
  "total": 2,
  "processed": 0
}
```

Source: /docs/create-user-import
Full schemas: /docs/openapi.json


---

# Flowg8 · User import progress

Read durable per-person results and invitation errors.

Queued work survives API restarts. Live invitations are processed globally at most once every two seconds, with retry/backoff and global cooldown after provider limits. Sandbox simulates provisioning and acceptance without Cognito or email. completed means all provisioning requests completed, not inbox delivery or first login. Profile IDs are available immediately; identityId can remain null until a real invitation is accepted.

Use an administrator session in Live or an administrator/developer session in Sandbox. Integration access requires a service-account key with BOTH organization:write and users:invite. Keys can access/retry only imports owned by the same service account. Access is rechecked during background processing.

## GET /v1/organization/user-imports/{importId}

Authentication: restricted integration key (scope: users:invite) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/organization/user-imports/10000000-0000-4000-8000-000000000016" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "id": "import-uuid",
  "status": "completed",
  "total": 2,
  "processed": 2
}
```

Source: /docs/get-user-import
Full schemas: /docs/openapi.json


---

# Flowg8 · Retry failed import invitations

Retry only failed invitations without duplicating people.

Use an administrator session in Live or an administrator/developer session in Sandbox. Integration access requires a service-account key with BOTH organization:write and users:invite. Keys can access/retry only imports owned by the same service account. Access is rechecked during background processing.

## POST /v1/organization/user-imports/{importId}/retry

Authentication: restricted integration key (scope: users:invite) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/organization/user-imports/10000000-0000-4000-8000-000000000016/retry" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "content-type: application/json" \
  --data-raw '{}'
```

## Response excerpt

```json
{
  "status": "queued"
}
```

Source: /docs/retry-user-import
Full schemas: /docs/openapi.json


---

# Flowg8 · Invitation status

List pending, invited and accepted users.

Service accounts require users:invite and can list/retry only invitations created by that same service account, including after key rotation. They cannot create admin invitations, assign approval groups or delegate credentials. Live invitations create real accounts; Sandbox invitations simulate provisioning and acceptance without sending emails.

## GET /v1/organization/invitations

Authentication: restricted integration key (scope: users:invite) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/organization/invitations" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "items": []
}
```

Source: /docs/invitations
Full schemas: /docs/openapi.json


---

# Flowg8 · Retry provisioning

Retry a pending invitation after a technical failure.

Returns the existing invitation after successful provisioning, without resetting an existing account password. It retries pending provisioning; this is not a password-reset or renewal endpoint. No new person is created.

Service accounts require users:invite and can list/retry only invitations created by that same service account, including after key rotation. They cannot create admin invitations, assign approval groups or delegate credentials. Live invitations create real accounts; Sandbox invitations simulate provisioning and acceptance without sending emails.

## POST /v1/organization/invitations/{invitationId}/retry

Authentication: restricted integration key (scope: users:invite) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/organization/invitations/invitationId/retry" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "content-type: application/json" \
  --data-raw '{}'
```

## Response excerpt

```json
{
  "status": "invited"
}
```

Source: /docs/retry-invitation
Full schemas: /docs/openapi.json


---

# Flowg8 · Build decisions into your product.

Define a flow. Publish a fixed version. Start a process with your own data, then follow every decision through the API.

Quickstart: link an approval group → create a designer flow → publish its draft → start a run with the published version ID → read its overview and history. Replace example IDs before sending requests.

JSON over HTTP under /v1. Local API: http://localhost:4000. Production API hosting is not provisioned by this sprint. Response examples are excerpts; OpenAPI describes the full contract.

Schema v2 supports typed fields, conditions, sequential approval groups and terminal outcomes. Schema v1 purchase flows remain supported. External approval links are supported. Outbound lifecycle webhooks are configured under Organization → Webhooks. Automatic requester-manager approval is supported with assignment=requester_manager. Parallel gates and automatic HR assignment are not available yet.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/access" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

Source: /docs/overview
Full schemas: /docs/openapi.json


---

# Flowg8 · Sandbox environments

Develop against isolated test data without affecting Live.

Use your Live organization ID with GET /v1/sandbox to discover the Sandbox workspace ID. All normal endpoints use that returned workspace ID in X-Organization-Id. Both modes use the same API base URL. API keys cannot discover or create environments.

Sandbox flows, versions, executions, decisions, groups, directory profiles, keys, audit history, AI budgets and idempotency records are separate from Live. Nothing is copied automatically. Live keys start with fg_sk_; Sandbox keys start with fg_test_. Keys cannot cross environments, even when supplied with a foreign workspace ID.

Each organization currently has one Sandbox. It includes 100 process starts per UTC calendar month, counted independently of the Live plan. Billing changes are only available in Live. Signed-in members retain their organizational permissions; removing their parent membership also removes Sandbox access and disables their Sandbox keys.

Sandbox policy: 100 successful starts per UTC calendar month, maximum 10 simultaneously open processes. Only starts that would wait for approval need an open slot. Open requests expire 7 days after creation (status expired; remaining gates cancelled). Process data is deleted 30 days after creation, including decisions, history and cached command responses. decisionExpiresAt and expiresAt expose fixed, non-extendable deadlines. Flow definitions, configuration and keys are retained. The Worker cleans in bounded batches every minute and at startup; expired data is inaccessible immediately even if cleanup is delayed.

Usage counters and minimal idempotency tombstones contain no execution payload and survive deletion. Expired command replays return 410 RUN_DATA_EXPIRED and cannot recreate the execution. Replayed retained Sandbox commands return current execution state, not an obsolete waiting snapshot. Completing, expiring or deleting processes does not refund monthly usage. Concurrent starts enforce both limits atomically.

Use synthetic data: Sandbox uses the real approval engine and approval groups. A Sandbox does not anonymize data or simulate every external service. Configured Sandbox lifecycle webhooks send real HTTPS requests to your test destination; approval emails stay in the test mailbox. AI remains a real DeutschlandGPT call subject to its normal limits.

## GET /v1/sandbox

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Active workspace membership required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/sandbox" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

Source: /docs/sandbox
Full schemas: /docs/openapi.json


---

# Flowg8 · Create a Sandbox

Ensure the automatically created Sandbox exists. Repeated and concurrent requests return the same environment.

Send the Live organization ID. No data is cloned and nested Sandboxes are rejected. Discover the returned environment.mode and environment.organizationId (the parent organization); organization.id is the isolated Sandbox workspace ID. This endpoint is naturally idempotent per organization and does not require Idempotency-Key.

## POST /v1/sandbox

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/sandbox" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "content-type: application/json" \
  --data-raw '{}'
```

Source: /docs/create-sandbox
Full schemas: /docs/openapi.json


---

# Flowg8 · Authentication

Use a restricted integration key on your server. Every workspace operation also requires X-Organization-Id.

Send Authorization: Bearer $FLOWG8_API_KEY. Administrators create expiring keys under API keys. Secrets are shown once, stored only as SHA-256 hashes and cannot be recovered. Keep them on your server.

Use POST /v1/auth/token to sign in without a browser, or use your normal Flowg8 web sign-in. Both issue FLOWG8_ACCESS_TOKEN. Flowg8 manages authentication; no separate identity-provider setup is required. Interactive actions use this access token, not an ID token. Key management, group linking, AI, billing, inbox and decisions require a signed-in Flowg8 user. Integration keys can never approve requests.

Keys are workspace-bound, expire after 1–365 days and can be revoked for subsequent requests. Keys with serviceAccountId are organization-owned and stay valid when the creator leaves; disabling the service account invalidates all its keys. Legacy keys without serviceAccountId are invalidated when their creator membership is deactivated. Revoke keys explicitly during offboarding.

Workspace access requires an enrolled authenticator. Complete /security in the browser first. Every API request validates the token online and refreshes group membership. Sign-out revokes all current Cognito sessions. API sign-in may return a standard MFA challenge.

## GET /v1/access

Authentication: restricted integration key (scope: any) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Active workspace membership required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/access" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

Source: /docs/authentication
Full schemas: /docs/openapi.json


---

# Flowg8 · Safe retries

Send a stable Idempotency-Key for each command. Retry with the same key and identical input.

Keys: 8–128 letters, digits, dots, underscores, colons or hyphens. Scoped to workspace, actor and operation. Reusing a key with different input returns 409. Generate a new key only for a new operation.

API-key creation retries return secret: null and replayed: true. If the first response was lost, revoke that key and create another. Search and AI questions do not use command idempotency.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/access" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

Source: /docs/idempotency
Full schemas: /docs/openapi.json


---

# Flowg8 · Errors & request IDs

Errors use RFC 9457 application/problem+json with type, title, status, detail, instance and the compatible error, message, requestId fields. Keep X-Request-Id for troubleshooting; honor Retry-After for 429/503.

400 invalid input; 401 invalid/expired credential; 402 quota or billing restriction; 403 missing role, membership or scope; 404 missing resource; 409 conflict/stale revision or Sandbox open limit/expired approval; 410 expired Sandbox command data; 429 AI limit; 502 invalid AI output; 503 dependency unavailable.

Reload the latest revision before resolving conflicts. Retry transient failures with bounded backoff and the original idempotency key. Never automatically retry a write with a fresh key.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/access" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "error": "CONFLICT",
  "message": "The draft has changed",
  "requestId": "example-request-id"
}
```

Source: /docs/errors
Full schemas: /docs/openapi.json


---

# Flowg8 · List flows

List workspace flows. Pass the returned nextCursor as the optional cursor query until it is null.



## GET /v1/flows

Authentication: restricted integration key (scope: flows:read) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Active workspace membership required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/flows" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "items": [
    {
      "id": "10000000-0000-4000-8000-000000000002",
      "name": "Deployment approval",
      "publishedVersion": 1
    }
  ],
  "nextCursor": null
}
```

Source: /docs/list-flows
Full schemas: /docs/openapi.json


---

# Flowg8 · Retrieve a flow

Read its editable draft and immutable versions. Starting a process uses a published version ID.



## GET /v1/flows/{flowId}

Authentication: restricted integration key (scope: flows:read) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Active workspace membership required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/flows/10000000-0000-4000-8000-000000000002" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "id": "10000000-0000-4000-8000-000000000002",
  "name": "Deployment approval",
  "versions": [
    {
      "id": "10000000-0000-4000-8000-000000000003",
      "version": 1,
      "publishedAt": "2026-10-17T08:00:00.000Z"
    }
  ],
  "draft": {
    "revision": 1,
    "publishedRevision": 1
  }
}
```

Source: /docs/get-flow
Full schemas: /docs/openapi.json


---

# Flowg8 · Create a flow

Create a named designer document with typed fields and a node graph. This saves a draft and does not start a process.

Replace the example groupId with an existing workspace approval group. Up to 30 fields (text, number, boolean, ISO date, select) and 40 nodes (start, condition, approval, end).

Conditions reference field keys with all/any and eq, neq, gt, gte, lt, lte or contains. Internal approval nodes reference groupId. External nodes use groupId:null and externalApprover:{source:"email",email:"reviewer@example.com"} or {source:"field",field:"recipientEmail",allowedDomains:["example.com"]}. The referenced field must be required text/email. sharedFields lists the request fields disclosed externally (default []). Connect all outputs before publishing. Loops and unreachable nodes are rejected.

Approval outputs: next selects the approved route; rejectedNext selects the rejected route. Connect both for new flows. Each may lead to a condition, another approval, or an end. Omitting rejectedNext preserves historical immediate rejection; null is an unconnected draft output and blocks publishing. Only gates on the actual decision path become pending.

Definition-only alternative: POST /v1/flows {name, definition}; POST /v1/flows/{flowId}/versions {definition}; POST /v1/flow-versions/{versionId}/publish {}. Both schema versions are supported.

## POST /v1/designer-flows

Authentication: restricted integration key (scope: flows:write) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- name (string, required): min length 1 · max length 120
- accessScope (string, optional): min length 1 · max length 60
- definition (object, required): 
- presentation (object, required): 

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/designer-flows" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-create-flow-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "name": "Deployment approval",
  "definition": {
    "schemaVersion": 2,
    "fields": [
      {
        "key": "environment",
        "label": "Environment",
        "type": "select",
        "required": true,
        "options": [
          "staging",
          "production"
        ],
        "min": null,
        "max": null
      }
    ],
    "nodes": [
      {
        "id": "start",
        "type": "start",
        "label": "Request received",
        "next": "approval"
      },
      {
        "id": "approval",
        "type": "approval",
        "label": "Operations approval",
        "groupId": "10000000-0000-4000-8000-000000000009",
        "next": "end"
      },
      {
        "id": "end",
        "type": "end",
        "label": "Approved",
        "outcome": "approved"
      }
    ]
  },
  "presentation": {
    "names": {
      "api": "Request",
      "amount": "Condition",
      "end": "Complete"
    },
    "description": "Operations approves a deployment.",
    "positions": {}
  }
}'
```

## Response excerpt

```json
{
  "id": "10000000-0000-4000-8000-000000000002",
  "draft": {
    "revision": 1,
    "publishedVersionId": null
  }
}
```

Source: /docs/create-flow
Full schemas: /docs/openapi.json


---

# Flowg8 · Update a draft

Save the full designer document with its current revision. Stale writes return 409.



## POST /v1/flows/{flowId}/draft

Authentication: restricted integration key (scope: flows:write) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- revision (integer, required): min 0 · max 9007199254740991
- document (object, required): 

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/flows/10000000-0000-4000-8000-000000000002/draft" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-save-draft-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "revision": 1,
  "document": {
    "name": "Deployment approval",
    "definition": {
      "schemaVersion": 2,
      "fields": [
        {
          "key": "environment",
          "label": "Environment",
          "type": "select",
          "required": true,
          "options": [
            "staging",
            "production"
          ],
          "min": null,
          "max": null
        }
      ],
      "nodes": [
        {
          "id": "start",
          "type": "start",
          "label": "Request received",
          "next": "approval"
        },
        {
          "id": "approval",
          "type": "approval",
          "label": "Operations approval",
          "groupId": "10000000-0000-4000-8000-000000000009",
          "next": "end"
        },
        {
          "id": "end",
          "type": "end",
          "label": "Approved",
          "outcome": "approved"
        }
      ]
    },
    "presentation": {
      "names": {
        "api": "Request",
        "amount": "Condition",
        "end": "Complete"
      },
      "description": "Operations approves a deployment.",
      "positions": {}
    }
  }
}'
```

## Response excerpt

```json
{
  "id": "10000000-0000-4000-8000-000000000002",
  "draft": {
    "revision": 2
  }
}
```

Source: /docs/save-draft
Full schemas: /docs/openapi.json


---

# Flowg8 · Publish a flow

Publish the saved draft revision. Existing executions keep their original version.

Use draft.publishedVersionId for new runs. Live publication requires a complete business profile and explicit activation; otherwise 409 ORGANIZATION_NOT_LIVE. Both publication APIs enforce this rule. Sandbox publication stays available. Publishing consumes no process quota and starts no execution.

## POST /v1/flows/{flowId}/publish

Authentication: restricted integration key (scope: flows:write) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- revision (integer, required): min 1 · max 9007199254740991

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/flows/10000000-0000-4000-8000-000000000002/publish" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-publish-flow-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "revision": 1
}'
```

## Response excerpt

```json
{
  "id": "10000000-0000-4000-8000-000000000002",
  "draft": {
    "publishedVersionId": "10000000-0000-4000-8000-000000000003",
    "publishedRevision": 1
  }
}
```

Source: /docs/publish-flow
Full schemas: /docs/openapi.json


---

# Flowg8 · Start a process

Start an execution of a published version. Data must match the version’s field definitions.

Optional documentIds contains ready reservations from the same starting identity and published flow version. Required fields, per-field counts, expiry and tenant are checked atomically. Each document can be bound to one run only. No document URL is included in run data.

flowVersionId: published version UUID, not a flow ID. referenceId: your system reference, 1–128 characters, unique per published version in the workspace. data: scalar values keyed by field key; unknown fields are rejected. Use idempotency to prevent duplicate starts.

One successfully started process consumes one request, regardless of API calls or gate count. Free includes 25 per monthly usage period. Existing processes can still complete after the start limit is reached.

Approval nodes can use assignment=requester_manager with groupId=null. An integration with runs:start may pass requesterPersonId (directory person ID). The direct manager must have active user access; missing assignments return 409 MANAGER_UNAVAILABLE. The recipient is frozen when the step activates.

Returns a receipt with data={} and an empty referenceId, including retries. Only assigned approvers/reviewers can subsequently retrieve submitted content.

## POST /v1/flow-runs

Authentication: restricted integration key (scope: runs:start) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Requester role required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- flowVersionId (string, required): uuid
- referenceId (string, required): min length 1 · max length 128
- requesterPersonId (string, optional): uuid
- data (object, required): 
- documentIds (array, optional): max items 100

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/flow-runs" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-start-run-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "flowVersionId": "10000000-0000-4000-8000-000000000003",
  "referenceId": "deployment-example-001",
  "data": {
    "environment": "production"
  }
}'
```

## Response excerpt

```json
{
  "id": "10000000-0000-4000-8000-000000000004",
  "status": "waiting",
  "gates": [
    {
      "id": "10000000-0000-4000-8000-000000000005",
      "status": "pending"
    }
  ]
}
```

Source: /docs/start-run
Full schemas: /docs/openapi.json


---

# Flowg8 · List executions

List executions. Optional query: status=waiting|approved|rejected|completed|expired and cursor=<nextCursor>.

Only active signed-in members of an assigned approval or acknowledgment group with a pending or completed task can read private content. Blocked/cancelled tasks, unassigned administrators, requesters and all API keys grant no content access. Current membership is checked on every request and replay. Lists and cursors obey the same boundary. New Live executions retain evidence for three calendar months on Free or twelve on paid plans after final completion; open Live executions do not expire by age. Existing longer deadlines remain protected. Sandbox content expires after 30 days from creation.

## GET /v1/flow-runs

Authentication: restricted integration key (scope: runs:read) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Matching approval group required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/flow-runs" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "items": [
    {
      "id": "10000000-0000-4000-8000-000000000004",
      "status": "waiting"
    }
  ],
  "nextCursor": null
}
```

Source: /docs/list-runs
Full schemas: /docs/openapi.json


---

# Flowg8 · Retrieve an execution

Read execution state, submitted data and gate tasks.

Only active signed-in members of an assigned approval or acknowledgment group with a pending or completed task can read private content. Blocked/cancelled tasks, unassigned administrators, requesters and all API keys grant no content access. Current membership is checked on every request and replay. Lists and cursors obey the same boundary. New Live executions retain evidence for three calendar months on Free or twelve on paid plans after final completion; open Live executions do not expire by age. Existing longer deadlines remain protected. Sandbox content expires after 30 days from creation.

## GET /v1/flow-runs/{runId}

Authentication: restricted integration key (scope: runs:read) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Matching approval group required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/flow-runs/10000000-0000-4000-8000-000000000004" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "id": "10000000-0000-4000-8000-000000000004",
  "status": "waiting",
  "data": {
    "environment": "production"
  },
  "gates": [
    {
      "id": "10000000-0000-4000-8000-000000000005",
      "status": "pending"
    }
  ]
}
```

Source: /docs/get-run
Full schemas: /docs/openapi.json


---

# Flowg8 · Execution overview

Retrieve the run, published flow metadata, history and v2 definition together.

Only active signed-in members of an assigned approval or acknowledgment group with a pending or completed task can read private content. Blocked/cancelled tasks, unassigned administrators, requesters and all API keys grant no content access. Current membership is checked on every request and replay. Lists and cursors obey the same boundary. New Live executions retain evidence for three calendar months on Free or twelve on paid plans after final completion; open Live executions do not expire by age. Existing longer deadlines remain protected. Sandbox content expires after 30 days from creation.

## GET /v1/flow-runs/{runId}/overview

Authentication: restricted integration key (scope: runs:read) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Matching approval group required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/flow-runs/10000000-0000-4000-8000-000000000004/overview" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "run": {
    "id": "10000000-0000-4000-8000-000000000004",
    "status": "waiting"
  },
  "flow": {
    "id": "10000000-0000-4000-8000-000000000002",
    "name": "Deployment approval",
    "version": 1
  },
  "history": []
}
```

Source: /docs/run-overview
Full schemas: /docs/openapi.json


---

# Flowg8 · Audit history

Read ordered audit events for an execution.

Only active signed-in members of an assigned approval or acknowledgment group with a pending or completed task can read private content. Blocked/cancelled tasks, unassigned administrators, requesters and all API keys grant no content access. Current membership is checked on every request and replay. Lists and cursors obey the same boundary. New Live executions retain evidence for three calendar months on Free or twelve on paid plans after final completion; open Live executions do not expire by age. Existing longer deadlines remain protected. Sandbox content expires after 30 days from creation.

## GET /v1/flow-runs/{runId}/history

Authentication: restricted integration key (scope: runs:read) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Matching approval group required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/flow-runs/10000000-0000-4000-8000-000000000004/history" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
[
  {
    "sequence": 1,
    "type": "run.started",
    "runId": "10000000-0000-4000-8000-000000000004",
    "details": {}
  }
]
```

Source: /docs/history
Full schemas: /docs/openapi.json


---

# Flowg8 · Approval inbox

List pending tasks the signed-in person may decide. Integration keys cannot access the inbox.

GET /v1/gate-tasks also lists permitted tasks. GET /v1/approvals includes both approvals and acknowledgments; filter with kind=approval|acknowledgment before cursor pagination. The signed-in Flowg8 user needs the gate’s assigned approval group. A directory person profile alone grants no approval permission.

## GET /v1/approvals

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Active workspace membership required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/approvals" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "items": [],
  "nextCursor": null
}
```

Source: /docs/approvals
Full schemas: /docs/openapi.json


---

# Flowg8 · Record a decision

Approve or reject a pending gate as its authorized person. The decision follows the gate’s approved or rejected route. Legacy flows end on rejection.

FLOWG8_ACCESS_TOKEN for a user with the gate’s assigned group required. Only the current pending gate can be decided. outcome: approved|rejected for approval; acknowledged for acknowledgment; optional comment up to 2,000 characters.

## POST /v1/gate-tasks/{taskId}/decisions

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Matching approval group required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- outcome (string, required): approved | rejected | acknowledged
- comment (string, optional): max length 2000 · default ""

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/gate-tasks/10000000-0000-4000-8000-000000000005/decisions" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-decide-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "outcome": "approved",
  "comment": "Deployment window confirmed."
}'
```

## Response excerpt

```json
{
  "id": "10000000-0000-4000-8000-000000000004",
  "status": "approved"
}
```

Source: /docs/decide
Full schemas: /docs/openapi.json


---

# Flowg8 · Approval groups

Read organization approval teams and your current decision permissions.



## GET /v1/approval-groups

Authentication: restricted integration key (scope: flows:read) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Active workspace membership required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/approval-groups" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "items": [
    {
      "id": "10000000-0000-4000-8000-000000000009",
      "name": "Operations",
      "revision": 1,
      "memberIds": [
        "10000000-0000-4000-8000-000000000006"
      ],
      "needsMemberReview": false
    }
  ],
  "canApprove": []
}
```

Source: /docs/groups
Full schemas: /docs/openapi.json


---

# Flowg8 · Create an approval group

Create a named approval team and select people from the organization directory.

Administrator user token required; Sandbox developers may manage Sandbox groups. memberIds are person IDs from GET /v1/organization/directory in the same organization/environment. Pending invitation profiles may be selected; decisions require a linked active user and active organization membership. Empty groups are allowed for preparation. Use the stable group ID in approval nodes. Requires Idempotency-Key.

## POST /v1/approval-groups

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- name (string, required): min length 1 · max length 80
- accessScope (string, optional): min length 1 · max length 60 · default "general"
- memberIds (array, optional): max items 1000 · default []

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/approval-groups" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-link-group-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "name": "Operations",
  "memberIds": [
    "10000000-0000-4000-8000-000000000006"
  ]
}'
```

## Response excerpt

```json
{
  "id": "10000000-0000-4000-8000-000000000009",
  "name": "Operations",
  "revision": 1,
  "memberIds": [
    "10000000-0000-4000-8000-000000000006"
  ],
  "needsMemberReview": false
}
```

Source: /docs/link-group
Full schemas: /docs/openapi.json


---

# Flowg8 · Update an approval group

Rename a group or replace its member selection with revision protection.

Use the latest revision and an Idempotency-Key. Member changes take effect on the next permission check, including gates already waiting. Removing a member does not undo an earlier decision. Group IDs and published flow definitions stay fixed. Integration keys cannot administer approval permissions. needsMemberReview signals a pre-existing assignment: saving replaces it with exactly the selected people.

## PUT /v1/approval-groups/{groupId}

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- name (string, required): min length 1 · max length 80
- accessScope (string, optional): min length 1 · max length 60 · default "general"
- memberIds (array, optional): max items 1000 · default []
- revision (integer, required): min 1 · max 9007199254740991

## Request example (replace example IDs)

```sh
curl -X PUT "https://api.flowg8.io/v1/approval-groups/10000000-0000-4000-8000-000000000009" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-update-group-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "name": "Operations",
  "memberIds": [
    "10000000-0000-4000-8000-000000000006"
  ],
  "revision": 1
}'
```

Source: /docs/update-group
Full schemas: /docs/openapi.json


---

# Flowg8 · Organization directory

Read people, units, reporting lines and HR contacts.

The founder is seeded automatically. Use Invite a user for login accounts; directory-only profiles create no logins and grant no approval rights. Manager and HR links are directory data; workflow gates do not yet resolve them dynamically.

## GET /v1/organization/directory

Authentication: restricted integration key (scope: organization:read) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Active workspace membership required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/organization/directory" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "organization": {
    "id": "10000000-0000-4000-8000-000000000001",
    "name": "Example workspace",
    "revision": 1
  },
  "people": [],
  "units": []
}
```

Source: /docs/directory
Full schemas: /docs/openapi.json


---

# Flowg8 · Create a person

Create a directory profile. Optional links default to null.

identityId explicitly links an existing active Flowg8 member, never automatically by email. Administrators list eligible members with GET /v1/organization/members.

## POST /v1/organization/people

Authentication: restricted integration key (scope: organization:write) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- displayName (string, required): min length 1 · max length 120
- email (string, optional): email · max length 254
- jobTitle (string, optional): max length 120 · default ""
- externalId (string, optional): min length 1 · max length 120 · default null
- unitId (string, optional): uuid · default null
- managerId (string, optional): uuid · default null
- hrPersonId (string, optional): uuid · default null
- identityId (string, optional): uuid · default null
- active (boolean, optional): default true

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/organization/people" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-create-person-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "displayName": "Alex Example",
  "email": null,
  "jobTitle": "Engineer",
  "externalId": "employee-example",
  "unitId": null,
  "managerId": null,
  "hrPersonId": null,
  "identityId": null,
  "active": true
}'
```

## Response excerpt

```json
{
  "people": [
    {
      "displayName": "Alex Example",
      "email": null,
      "jobTitle": "Engineer",
      "externalId": "employee-example",
      "unitId": null,
      "managerId": null,
      "hrPersonId": null,
      "identityId": null,
      "active": true,
      "id": "10000000-0000-4000-8000-000000000006",
      "revision": 1
    }
  ]
}
```

Source: /docs/create-person
Full schemas: /docs/openapi.json


---

# Flowg8 · Update a person

Replace all editable person fields and send the current revision.

Send full input fields, not id, createdAt or updatedAt. Cycles, inactive references, foreign workspace links and stale revisions are rejected.

## PUT /v1/organization/people/{personId}

Authentication: restricted integration key (scope: organization:write) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- displayName (string, required): min length 1 · max length 120
- email (string, required): email · max length 254
- jobTitle (string, required): max length 120 · default ""
- externalId (string, required): min length 1 · max length 120 · default null
- unitId (string, required): uuid · default null
- managerId (string, required): uuid · default null
- hrPersonId (string, required): uuid · default null
- identityId (string, required): uuid · default null
- active (boolean, required): default true
- revision (integer, required): min 1 · max 9007199254740991

## Request example (replace example IDs)

```sh
curl -X PUT "https://api.flowg8.io/v1/organization/people/10000000-0000-4000-8000-000000000006" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-update-person-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "displayName": "Alex Example",
  "email": null,
  "jobTitle": "Senior engineer",
  "externalId": "employee-example",
  "unitId": null,
  "managerId": null,
  "hrPersonId": null,
  "identityId": null,
  "active": true,
  "revision": 1
}'
```

## Response excerpt

```json
{
  "people": [
    {
      "displayName": "Alex Example",
      "email": null,
      "jobTitle": "Engineer",
      "externalId": "employee-example",
      "unitId": null,
      "managerId": null,
      "hrPersonId": null,
      "identityId": null,
      "active": true,
      "id": "10000000-0000-4000-8000-000000000006",
      "revision": 2
    }
  ]
}
```

Source: /docs/update-person
Full schemas: /docs/openapi.json


---

# Flowg8 · Create a unit

Create an organizational unit, optionally beneath an active unit.



## POST /v1/organization/units

Authentication: restricted integration key (scope: organization:write) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- name (string, required): min length 1 · max length 120
- externalId (string, optional): min length 1 · max length 120 · default null
- parentId (string, optional): uuid · default null
- active (boolean, optional): default true

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/organization/units" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-create-unit-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "name": "Engineering",
  "externalId": "engineering",
  "parentId": null,
  "active": true
}'
```

## Response excerpt

```json
{
  "units": [
    {
      "name": "Engineering",
      "externalId": "engineering",
      "parentId": null,
      "active": true,
      "id": "10000000-0000-4000-8000-000000000007",
      "revision": 1
    }
  ]
}
```

Source: /docs/create-unit
Full schemas: /docs/openapi.json


---

# Flowg8 · Update a unit

Replace all editable unit fields using the current revision.



## PUT /v1/organization/units/{unitId}

Authentication: restricted integration key (scope: organization:write) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- name (string, required): min length 1 · max length 120
- externalId (string, required): min length 1 · max length 120 · default null
- parentId (string, required): uuid · default null
- active (boolean, required): default true
- revision (integer, required): min 1 · max 9007199254740991

## Request example (replace example IDs)

```sh
curl -X PUT "https://api.flowg8.io/v1/organization/units/10000000-0000-4000-8000-000000000007" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-update-unit-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "name": "Platform engineering",
  "externalId": "engineering",
  "parentId": null,
  "active": true,
  "revision": 1
}'
```

## Response excerpt

```json
{
  "units": [
    {
      "name": "Engineering",
      "externalId": "engineering",
      "parentId": null,
      "active": true,
      "id": "10000000-0000-4000-8000-000000000007",
      "revision": 2
    }
  ]
}
```

Source: /docs/update-unit
Full schemas: /docs/openapi.json


---

# Flowg8 · Rename a workspace

Use the organization revision from the directory.



## PUT /v1/organization

Authentication: restricted integration key (scope: organization:write) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- name (string, required): min length 1 · max length 120
- revision (integer, required): min 1 · max 9007199254740991

## Request example (replace example IDs)

```sh
curl -X PUT "https://api.flowg8.io/v1/organization" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-rename-workspace-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "name": "Example workspace",
  "revision": 1
}'
```

## Response excerpt

```json
{
  "organization": {
    "id": "10000000-0000-4000-8000-000000000001",
    "name": "Example workspace",
    "revision": 2
  }
}
```

Source: /docs/rename-workspace
Full schemas: /docs/openapi.json


---

# Flowg8 · Read responsibilities

Read the recorded manager and HR contact for a person.



## GET /v1/organization/people/{personId}/responsibilities

Authentication: restricted integration key (scope: organization:read) or Flowg8 sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Active workspace membership required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/organization/people/10000000-0000-4000-8000-000000000006/responsibilities" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "personId": "10000000-0000-4000-8000-000000000006",
  "manager": null,
  "hr": null
}
```

Source: /docs/responsibilities
Full schemas: /docs/openapi.json


---

# Flowg8 · API keys

List key metadata as a signed-in administrator. Listing never returns secrets.

Scopes: flows:read, flows:write, runs:read, runs:start, organization:read, organization:write. Write also includes read for the same resource. A start-only key cannot read flows or runs without additional scopes.

## GET /v1/api-keys

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/api-keys" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "items": []
}
```

Source: /docs/api-keys
Full schemas: /docs/openapi.json


---

# Flowg8 · Create an API key

Create a restricted server credential with an expiry or an explicit service-account exception. Store the secret from the first response securely.

Expiry: 1–365 days, default 30. Set expiresInDays to null only with an active serviceAccountId to issue a key without expiration. Such keys remain valid until revoked; restrict their permissions and replace them regularly. Maximum 200 records per workspace including revoked keys. Secrets are never replayed. Revoke and replace lost keys.

Set serviceAccountId for organization-owned keys. Every requested scope must fit the active account permission ceiling; users:invite always requires a service account. Secrets are shown once. Create a second key and revoke the first for rotation.

## POST /v1/api-keys

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- name (string, required): min length 1 · max length 80
- scopes (array, required): min items 1 · max items 7
- serviceAccountId (string, optional): uuid
- expiresInDays (integer, optional): min 1 · max 365 · default 30

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/api-keys" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-create-key-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "name": "Deployment integration",
  "scopes": [
    "runs:start",
    "runs:read",
    "flows:read"
  ],
  "expiresInDays": 30,
  "serviceAccountId": "10000000-0000-4000-8000-000000000010"
}'
```

## Response excerpt

```json
{
  "key": {
    "id": "10000000-0000-4000-8000-000000000008",
    "name": "Deployment integration"
  },
  "secret": "<shown only on first creation>",
  "replayed": false
}
```

Source: /docs/create-key
Full schemas: /docs/openapi.json


---

# Flowg8 · Revoke an API key

Revoke a key as an administrator. Subsequent calls using it are rejected.



## POST /v1/api-keys/{keyId}/revoke

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/api-keys/10000000-0000-4000-8000-000000000008/revoke" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-revoke-key-001" \
  -H "content-type: application/json" \
  --data-raw '{}'
```

## Response excerpt

```json
{
  "id": "10000000-0000-4000-8000-000000000008",
  "revokedAt": "2026-10-17T08:00:00.000Z"
}
```

Source: /docs/revoke-key
Full schemas: /docs/openapi.json


---

# Flowg8 · Generate a draft with AI

Suggest a validated document. An administrator must review and save it explicitly.

DeutschlandGPT uses a verified EU-hosted configured model. Supports approval, acknowledgment, notification, document fields and approved/rejected/completed ends. This does not publish or execute anything.

AI is disabled by default per organization and environment. An administrator must explicitly enable external AI processing under Organization → Privacy. Never include credentials or confidential personal information. Local keyword search remains available with smart=false.

## POST /v1/ai/flow-suggestions

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- prompt (string, required): min length 12 · max length 3000
- locale (string, optional): en | de · default "en"

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/ai/flow-suggestions" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "content-type: application/json" \
  --data-raw '{
  "prompt": "Operations approves every production deployment. Ask for environment and release version.",
  "locale": "en"
}'
```

## Response excerpt

```json
{
  "questions": [],
  "warnings": []
}
```

Source: /docs/generate-flow
Full schemas: /docs/openapi.json


---

# Flowg8 · Search flows

Find flows by keywords or optional AI query expansion.

If AI is unavailable or limited, search falls back to keywords and returns degraded: true. Keys use GET /v1/flows instead.

AI is disabled by default per organization and environment. An administrator must explicitly enable external AI processing under Organization → Privacy. Never include credentials or confidential personal information. Local keyword search remains available with smart=false.

## POST /v1/flows/search

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Active workspace membership required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- query (string, required): min length 2 · max length 200
- smart (boolean, optional): default false

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/flows/search" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "content-type: application/json" \
  --data-raw '{
  "query": "production deployment approval",
  "smart": true
}'
```

## Response excerpt

```json
{
  "items": [],
  "terms": [
    "deployment"
  ],
  "mode": "keyword",
  "degraded": true
}
```

Source: /docs/search-flows
Full schemas: /docs/openapi.json


---

# Flowg8 · Ask the docs

Ask implementation questions grounded in this reference. Sign in to use the assistant.

Only your question and public docs go to DeutschlandGPT. No workspace records, session tokens or API keys are supplied as context. Never include secrets or personal data. Known credential formats are blocked before sending. Answers are suggestions with sources, not executed commands.

AI is disabled by default per organization and environment. An administrator must explicitly enable external AI processing under Organization → Privacy. Never include credentials or confidential personal information. Local keyword search remains available with smart=false.

## POST /v1/ai/docs-questions

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Active workspace membership required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- question (string, required): min length 5 · max length 2000
- topic (string, required): integrations | create-integration | update-integration | domains | add-domain | verify-domain | run-actions | retry-action | email-ingress | edit-flow | step-types | notifications | documents | document-upload | document-confirm | document-link | document-list | document-content | received-email | external-received-email | external-document-list | external-document-content | business-profile | save-business-profile | activate-live | webhooks | create-webhook | update-webhook | rotate-webhook-secret | webhook-deliveries | retry-webhook-delivery | external-resolve | external-decide | external-status | external-resend | sandbox-mailbox | service-accounts | create-service-account | update-service-account | sandbox-developers | set-sandbox-developer | postman | obtain-token | refresh-token | auth-challenge | register-account | confirm-account | workspace | workspaces | invite-user | invitations | retry-invitation | accept-sandbox-invitation | validate-user-import | create-user-import | get-user-import | retry-user-import | overview | sandbox | create-sandbox | authentication | idempotency | errors | list-flows | get-flow | create-flow | save-draft | publish-flow | start-run | list-runs | get-run | run-overview | history | approvals | decide | groups | link-group | update-group | directory | create-person | update-person | create-unit | update-unit | rename-workspace | responsibilities | api-keys | create-key | revoke-key | generate-flow | search-flows | ask-docs | limits
- locale (string, optional): en | de · default "en"

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/ai/docs-questions" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "content-type: application/json" \
  --data-raw '{
  "question": "How do I start a published flow safely?",
  "topic": "start-run",
  "locale": "en"
}'
```

## Response excerpt

```json
{
  "answer": "Use POST /v1/flow-runs with a published version ID and a stable Idempotency-Key.",
  "sources": [
    "start-run",
    "idempotency"
  ]
}
```

Source: /docs/ask-docs
Full schemas: /docs/openapi.json


---

# Flowg8 · Limits & capabilities

Know the boundaries before integrating. OpenAPI is the full machine-readable schema.

Security policy: only assigned authenticated approvers/reviewers may access private process content. Guest approvals, external document references and outbound sharedFields are disabled. Use private uploads and static outbound notifications. New Live executions retain evidence for three calendar months on Free or twelve on paid plans after final completion; open Live executions do not expire by age. Existing longer deadlines remain protected. Sandbox remains at 30 days from creation.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/access" \
  -H "authorization: Bearer $FLOWG8_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

Source: /docs/limits
Full schemas: /docs/openapi.json


---

# Flowg8 · Service accounts

List organization-owned integration identities in the selected environment.

Live administrators manage Live accounts. Administrators and explicitly granted Sandbox developers manage Sandbox accounts. Service keys cannot manage accounts, grant access, create keys or approve gates. An account belongs to exactly one workspace and environment.

## GET /v1/service-accounts

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/service-accounts" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "items": [
    {
      "id": "10000000-0000-4000-8000-000000000010",
      "name": "ERP onboarding",
      "scopes": [
        "users:invite"
      ],
      "active": true,
      "revision": 1
    }
  ]
}
```

Source: /docs/service-accounts
Full schemas: /docs/openapi.json


---

# Flowg8 · Create a service account

Create an integration identity with an explicit permission ceiling.

Create the account with a user token, then issue API keys with serviceAccountId using Create an API key. Account creation returns metadata, never a credential. Each key may request a subset of the normalized account scopes. flows:write includes flows:read; organization:write includes organization:read. Up to 100 accounts per workspace.

## POST /v1/service-accounts

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- name (string, required): min length 1 · max length 80
- scopes (array, required): min items 1 · max items 7

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flowg8.io/v1/service-accounts" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-create-service-account-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "name": "ERP onboarding",
  "scopes": [
    "users:invite"
  ]
}'
```

## Response excerpt

```json
{
  "id": "10000000-0000-4000-8000-000000000010",
  "name": "ERP onboarding",
  "scopes": [
    "users:invite"
  ],
  "active": true,
  "revision": 1
}
```

Source: /docs/create-service-account
Full schemas: /docs/openapi.json


---

# Flowg8 · Update a service account

Rename, restrict, disable or re-enable an integration identity.

Send the current revision. Disabling an account invalidates every attached key on subsequent requests. Reducing its scopes invalidates keys exceeding the new ceiling. Re-enabling or widening permissions can make non-revoked, unexpired keys usable again. Explicitly revoke individual keys to prevent reuse. Creator membership is audit metadata: service keys continue when the human creator leaves. Legacy keys without serviceAccountId retain their creator-bound behavior.

## PUT /v1/service-accounts/{serviceAccountId}

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- name (string, required): min length 1 · max length 80
- scopes (array, required): min items 1 · max items 7
- active (boolean, required): 
- revision (integer, required): min 1 · max 9007199254740991

## Request example (replace example IDs)

```sh
curl -X PUT "https://api.flowg8.io/v1/service-accounts/10000000-0000-4000-8000-000000000010" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-update-service-account-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "name": "ERP onboarding",
  "scopes": [
    "users:invite"
  ],
  "active": false,
  "revision": 1
}'
```

Source: /docs/update-service-account
Full schemas: /docs/openapi.json


---

# Flowg8 · Sandbox developer access

List existing active human members and their separate Sandbox developer grant.

Live administrator user token and Live organization ID required. Invite and accept a member first, then select their identityId. Access changes affect neither Live roles nor approval-group membership. Sandbox still enforces normal quotas and retention.

## GET /v1/sandbox/developers

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator role required · Live only. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/sandbox/developers" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "items": [
    {
      "identityId": "10000000-0000-4000-8000-000000000011",
      "displayName": "Alex Developer",
      "email": "alex@example.com",
      "enabled": false
    }
  ]
}
```

Source: /docs/sandbox-developers
Full schemas: /docs/openapi.json


---

# Flowg8 · Set Sandbox developer access

Grant or remove development access without granting Live administration.

Removing a grant immediately revokes personal Sandbox keys and disables service accounts created by that developer in Sandbox. It does not change independent Live service accounts.

## PUT /v1/sandbox/developers/{identityId}

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator role required · Live only. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- enabled (boolean, required): 

## Request example (replace example IDs)

```sh
curl -X PUT "https://api.flowg8.io/v1/sandbox/developers/10000000-0000-4000-8000-000000000011" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-set-sandbox-developer-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "enabled": true
}'
```

Source: /docs/set-sandbox-developer
Full schemas: /docs/openapi.json