# Organization

The organisation's own settings: its display name, its company email domains and whether Drift protection is on.

The organisation's own settings: its display name, its company email domains and whether Drift protection is on. One per tenant, named default. A field left out is left as it is. Applying needs an owner or admin. Deleting the document only stops managing these settings: the organisation itself is never deleted, and the settings keep their values.

| | |
|---|---|
| `apiVersion` | `vulnetix.com/v1` |
| `kind` | `Organization` |
| Group | [Org](/platform-iac/kinds/catalogue.md#org) |
| Status | **Served.** The [config engine](/platform-iac/reference/engine.md) plans and applies it. |
| Objects per tenant | one (`metadata.name: default`) |
| Token and role | An owner, or a person or service account with the developer role, or an Authentik access token for either. As code a developer grants up to developer and cannot change or remove an owner; in the console only an owner manages this kind. A member is refused with HTTP 403. See [Credentials for automation](/platform-iac/reference/config-api.md#credentials-for-automation). |
| Terraform resource | [`vulnetix_organization`](/platform-iac/terraform/resources.md#vulnetix_organization), imported by name (see [Terraform and OpenTofu](#terraform-and-opentofu)) |
| CLI | [`vulnetix config apply`](/platform-iac/cli/apply.md), CLI v3.168.0 and later. |
| Pinned schema | [`v1.19.1/Organization.schema.json`](https://github.com/Vulnesis/config-schemas/releases/download/v1.19.1/Organization.schema.json) |
| Newest schema | [`latest/Organization.schema.json`](https://github.com/Vulnesis/config-schemas/releases/latest/download/Organization.schema.json) |
| First released in | [`v1.5.0`](https://github.com/Vulnesis/config-schemas/releases/tag/v1.5.0) |
| Print the built-in copy | `vulnetix config schema Organization` |

## Minimal

Only the fields the kind requires. From `examples/Organization/minimal.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/Organization.schema.json
apiVersion: vulnetix.com/v1
kind: Organization
metadata:
  name: default
spec: {}
```

**HCL** (resource `vulnetix_organization`)

```hcl
# Only the arguments the kind requires. From config-schemas examples/Organization/minimal.yaml.

resource "vulnetix_organization" "default" {
}
```

Every field that has a schema default, set to that default: [`terraform/organization.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/organization.tf) and [`yaml/Organization.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/Organization.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/Organization.schema.json
apiVersion: vulnetix.com/v1
kind: Organization
metadata:
  name: default
spec: {}
EOF
```

## Advanced

Every field the kind supports, with a `when` expression where it takes one. From `examples/Organization/advanced.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/Organization.schema.json
apiVersion: vulnetix.com/v1
kind: Organization
metadata:
  name: default
  labels:
    team: platform
  annotations:
    ticket: https://tracker.example.com/ORG-12
spec:
  displayName: Acme Corporation
  companyEmailDomains:
    - acme.com
    - acme.co.uk
  driftProtection: true
```

**HCL** (resource `vulnetix_organization`)

```hcl
# Every argument the kind supports. From config-schemas examples/Organization/advanced.yaml.

resource "vulnetix_organization" "default" {
  company_email_domains = ["acme.com", "acme.co.uk"]
  display_name          = "Acme Corporation"
  drift_protection      = true
  labels = {
    team = "platform"
  }
  annotations = {
    ticket = "https://tracker.example.com/ORG-12"
  }
}
```

Every field that has a schema default, set to that default: [`terraform/organization.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/organization.tf) and [`yaml/Organization.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/Organization.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/Organization.schema.json
apiVersion: vulnetix.com/v1
kind: Organization
metadata:
  name: default
  labels:
    team: platform
  annotations:
    ticket: https://tracker.example.com/ORG-12
spec:
  displayName: Acme Corporation
  companyEmailDomains:
    - acme.com
    - acme.co.uk
  driftProtection: true
EOF
```

## Fields

Paths use dots for nesting and `[]` for the items of a list. **Required** means required whenever the parent object is present. A default is what the server uses when the field is left out.

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| <span id="apiVersion"></span>`apiVersion` | string | yes |  | exactly `vulnetix.com/v1` | The document format version. Every kind in this release is vulnetix.com/v1. |
| <span id="kind"></span>`kind` | string | yes |  | exactly `Organization` | Always Organization. |
| <span id="metadata"></span>`metadata` | object | yes |  | no other keys | Metadata for a kind the tenant has exactly one of. The name is fixed to default. |
| <span id="metadata-name"></span>`metadata.name` | string | yes |  | exactly `default`; pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` | The object's name, unique per kind within a tenant. It is the natural key: plan, apply, export and the Terraform provider all address an object by kind and name. |
| <span id="metadata-org"></span>`metadata.org` | string | no |  | format `uuid` | The tenant (organization UUID) the document belongs to. When set, plan and apply refuse to run against any other tenant. |
| <span id="metadata-labels"></span>`metadata.labels` | object | no |  | map of string to string (length 0 to 256); keys match `^[a-z0-9]([a-z0-9._/-]{0,61}[a-z0-9])?$` | Free key/value labels. Stored with the object, never interpreted by the server. |
| <span id="metadata-annotations"></span>`metadata.annotations` | object | no |  | map of string to string (length 0 to 4096) | Free key/value notes for people and tools, such as a ticket link. |
| <span id="spec"></span>`spec` | object | yes |  | no other keys |  |
| <span id="spec-displayName"></span>`spec.displayName` | string | no |  | pattern `\S`; length 1 to 128 | The organisation's name as people see it, such as Acme Corporation. It is kept on the organisation's identity group, where it was set from the company name, or the email domain, when the organisation was created. |
| <span id="spec-companyEmailDomains"></span>`spec.companyEmailDomains` | array of string | no |  | 0 to 32 items; items unique; each item: pattern `^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$`; length 0 to 253 | The organisation's own email domains, such as acme.com. The Contributors page classes a contributor whose commit email is at one of these domains as internal, and everyone else as external. An empty list clears them, which means not configured: no contributor is classed either way. |
| <span id="spec-driftProtection"></span>`spec.driftProtection` | boolean | no | `false` |  | Whether the console and the legacy APIs refuse changes to settings that are managed by Platform IaC. false is advisory only: the console shows which settings are managed as code and still lets an owner or admin change them. true enforces it: a write from the console, an ApiKey or a legacy endpoint to a kind that has an object managed by Terraform or GitOps is refused with HTTP 409 managed_by_platform_iac. Writes from Platform IaC (the config API, under /v1/config) are never refused, and neither is this setting, so an owner or admin can always turn it off. |

## Applying this kind

- **Command.** `vulnetix config apply -f <file>`; the CLI line above says from which release. Plan first with [`vulnetix config plan`](/platform-iac/cli/plan.md): it shows each object as create, update, delete or no change, with a `planHash` that apply then holds to. Apply writes in one transaction.
- **Manager.** Each object records the manager that applied it (`terraform`, `console` or `gitops:<repo>`). `--prune` deletes only objects its own manager owns. See [The manager](/platform-iac/cli/plan.md#the-manager) and the [config engine](/platform-iac/reference/engine.md).
- **Status.** Applied, Unchanged or Deleted, with no other status fields. The phases the engine reports are explained under [status phases](/platform-iac/reference/engine.md#status-phases).
- **Singleton.** There is one per tenant, and its name is always `default`.

## How apply treats it

- `driftProtection` is the [Drift protection](/platform-iac/guides/drift-protection.md) switch. It always reads back (`false` before the server's migration), `true` is refused until that migration is applied, and the setting is never refused by Drift protection itself, so an owner or admin can always turn it off. Turning it on makes the Resolve Platform and the legacy APIs answer `409 managed_by_platform_iac` to a write to a managed kind.
- A singleton that merges: a field left out is left as it is.
- Domains are written with the account page's writer on the tenant row. Before the column's migration they read as absent and a write is refused.
- The display name is patched on the Authentik group `org-<slug>` (attribute `display_name`). That write registers an undo that puts the old name back when the apply does not commit.
- Owner or admin only. Delete lets go: the tenant is never deleted.

> [!CAREFUL] Per principal or per tenant
> `companyEmailDomain` is per principal on the account page, while the factory delivery sweep reads the tenant row. The engine writes the tenant row. In a single-person organization they are the same row.

## Terraform and OpenTofu

The resource is `vulnetix_organization` in the `vulnetix/resolve` provider. Its arguments are the `spec` in snake case, beside `name`, `labels` and `annotations` from `metadata`. The Minimal and Advanced HCL are above. The provider's own reference is [vulnetix_organization](https://registry.terraform.io/providers/vulnetix/resolve/latest/docs/resources/organization).

Import an object that already exists by its name (`default`):

```shell
# Import an existing Organization by its name (metadata.name).
terraform import vulnetix_organization.default default
```

Install, authentication and how state is read: [Terraform and OpenTofu](/platform-iac/terraform.md).

Check a file with `vulnetix config validate -f <file>`. See [Validate documents](/platform-iac/cli/validate.md). In an editor, start the file with the [schema comment](/platform-iac/schemas/editors.md).
