> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations & Projects

> Declare your projects, their members, and each project’s resources as config and provision your whole organization from one git repo

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`.

<Note>
  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.
</Note>

## The `kind: project` resource

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

```yaml roark/projects/payments-prod.yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# 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.

<Note>
  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](/documentation/integrations/okta).
</Note>

## Deploying

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

<Steps>
  <Step title="Authenticate with the organization key">
    ```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    export ROARK_API_BEARER_TOKEN="<your-organization-api-key>"
    ```
  </Step>

  <Step title="Preview">
    ```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    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.
  </Step>

  <Step title="Apply">
    ```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    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.
  </Step>
</Steps>

### Raw HTTP

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

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
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`:

```json theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
{
  "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.

<Warning>
  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`.
</Warning>

## 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

1. Keep a `roark/projects/` directory in git, one file per project, reviewed via pull requests.
2. 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.
3. 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.