Organizations & Projects

Everything else in Config as Code manages resources inside one project, authenticated by a project API key. This page is the level above: with an Organization API key you declare the projects your organization should have, each with its members and roles and its own nested resources, and apply the whole tree with the same roark config apply. This is how you run Config as Code at scale: one git repo, reviewed by PR, that provisions projects, onboards people, and configures each project, for the entire organization.

The two scopes

There is one apply surface (/v1/config, roark config apply); the credential decides what you may declare:

Your key	You declare	Lands in
Project API key	Project resources (`agent`, `persona`, `flow`, `metric`, …)	that one project
Organization API key	`kind: project` (with nested members and resources)	the whole organization

A project key cannot declare kind: project; an organization key declares only kind: project (project-scoped resources go under a project’s resources:).

Prerequisites

An Organization API key. An org Owner or Admin creates one under Settings → Organization → API keys (“New Key”). The full key is shown once, so store it in your secret manager. It carries org-config:apply and the project/member/api-key management permissions.
A git repository to hold your config.
The Roark CLI (recommended): npm install -g @roarkanalytics/cli.

An organization key is an admin credential: it can create projects, manage members, and mint per-project keys across your whole organization. Treat it like one, and prefer a read-only key (below) for CI dry-runs.

The `kind: project` resource

One file per project. A project declares its identity, its members, and (optionally) its own resources.

roark/projects/payments-prod.yaml

# yaml-language-server: $schema=https://roark.ai/roark-config.schema.json
kind: project
name: payments-prod                 # identity (configKey = project/<name>), lowercase slug
displayName: Payments (prod)        # optional; the project name shown in the UI
description: Production VA for payments
category: FINANCIAL                 # optional; HEALTHCARE | FINANCIAL | RETAIL | ... | OTHER
dataStorageRegion: US_EAST_1        # optional; US_EAST_1 | EU_WEST_1

members:
  - { email: jane@example.com, role: ADMIN }
  - { email: sam@example.com, role: MEMBER }

resources:                          # this project's own Config-as-Code resources
  - kind: agent
    name: payments-va
  - kind: metric
    name: refund_policy_accuracy
    type: BOOLEAN
    prompt: |
      Using {{transcript}} and {{world_context}}, was the refund policy stated correctly?

name is the stable identity (configKey = project/<name>) and the seed for the project slug. displayName is the human name in the UI (defaults to name).
members are reconciled by email: a new email is invited, an existing member’s role is updated, and (with prune on) a config-managed member you remove is removed. An existing UI or SSO member you declare is adopted rather than duplicated. Roles are the project roles: OWNER, ADMIN, MEMBER, VIEWER.
resources is the project’s own resource set, exactly the shapes documented on the other Config as Code pages (agents, personas, flows, metrics, collectors, simulation plans, alerts). They are applied into this project through the same reconcile, so one organization key manages an entire org’s config in one tree.

Prefer SCIM + SAML SSO for day-to-day user lifecycle at scale (automatic provisioning/deprovisioning and project auto-join from your IdP). Use members: here for the projects and roles you want declared in git; the two compose. See Okta SSO.

Deploying

Same commands as project config; the organization key is what puts them in org mode.

Authenticate with the organization key

export ROARK_API_BEARER_TOKEN="<your-organization-api-key>"

Preview

roark config diff ./roark/projects

The diff is a flat list: each project, its member changes, and its nested resource changes, tagged with the owning project.

Apply

roark config apply ./roark/projects --yes

Reconciles the whole tree: creates/updates projects, invites/updates members, applies each project’s resources, and (unless --no-prune) removes config-managed projects and members you deleted from git.

Raw HTTP

The bundle and endpoints are the same as project config; you just send it with the organization key.

curl -X POST https://api.roark.ai/v1/config/apply \
  -H "Authorization: Bearer $ROARK_API_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @bundle.json

Each change comes back with a status (applied / skipped / failed) and, for a project, its id. Member and nested-resource changes carry the owning project:

{
  "data": {
    "changes": [
      { "configKey": "project/payments-prod", "kind": "project", "name": "payments-prod", "op": "create", "status": "applied", "id": "..." },
      { "configKey": "member/jane@example.com", "kind": "member", "name": "jane@example.com", "op": "create", "status": "applied", "project": "payments-prod" },
      { "configKey": "agent/payments-va", "kind": "agent", "name": "payments-va", "op": "create", "status": "applied", "project": "payments-prod" }
    ],
    "summary": { "create": 3, "update": 0, "delete": 0, "noop": 0, "failed": 0 }
  }
}

Apply semantics

Identity is by name (project/<name>). Re-applying an unchanged project is a no-op, not a rewrite. Members reconcile by email.
Prune removes what you deleted. With prune on (the default), a project or member you remove from git is removed from Roark. Submit the full desired set every time, or use --no-prune / "prune": false for additive-only applies.

With prune enabled, deleting a kind: project file removes that project (and its data) on the next apply. Keep your repo the complete source of truth, or apply with --no-prune.

Imperative provisioning (REST)

For one-off or scripted provisioning outside the declarative flow, the organization key also drives a small REST surface. Config-as-code is the recommended path for GitOps; these are handy for automation that isn’t file-based.

Endpoint	Purpose
`GET/POST /v1/org/project`, `PUT/DELETE /v1/org/project/{id}`	List, create, update, delete projects
`GET/POST /v1/org/project/{id}/member`, `PUT/DELETE .../member/{id}`	List, invite, update role, remove members
`GET/POST /v1/org/project/{id}/api-key`, `DELETE .../api-key/{id}`	List, generate, revoke a per-project API key

Generating a per-project key is how you hand each team or environment its own project-scoped credential from your provisioning pipeline.

Recommended workflow

Keep a roark/projects/ directory in git, one file per project, reviewed via pull requests.
In CI, run roark config diff ./roark/projects on every PR (a read-only organization key is enough for diff) and post the output for review.
On merge, run roark config apply ./roark/projects --yes with a read+write organization key stored as a secret.

Teams get self-service projects, members, and configuration through a PR they own; you get a versioned, reviewable, reproducible organization with a full audit trail in git.

Getting Started

Simulations

Observability

Metrics

Config as Code

Autoimprove

Recipes

Integrations

Enterprise

SDKs & Developer Tools

Resources

Organizations & Projects

The two scopes

Prerequisites

The `kind: project` resource

Deploying

Raw HTTP

Apply semantics

Imperative provisioning (REST)

Recommended workflow

​The two scopes

​Prerequisites

​The kind: project resource

​Deploying

​Raw HTTP

​Apply semantics

​Imperative provisioning (REST)

​Recommended workflow

The two scopes

Prerequisites

The `kind: project` resource

Deploying

Raw HTTP

Apply semantics

Imperative provisioning (REST)

Recommended workflow