# Organizations

An organization is the top-level tenant container in Scribase. It holds
projects, members, environments, and the audit log. All resource paths are
scoped under an organization ID.

## Organization ID rules

- Lowercase alphanumeric and hyphens only.
- 2–64 characters.
- Must start and end with an alphanumeric character.

## Endpoints

### PUT /v1/organizations/{organization_id}

Create or update an organization.

**Request body:**

```json
{ "display_name": "Acme Platform" }
```

**Response `200 OK`:**

```json
{
  "id": "acme",
  "display_name": "Acme Platform",
  "created_at": "2026-01-01T00:00:00Z"
}
```

**Headers required:** `Idempotency-Key`

**Example:**

```sh
scribase org put acme "Acme Platform"
```

---

### GET /v1/organizations/{organization_id}

Read an organization record.

**Response `200 OK`:**

```json
{
  "id": "acme",
  "display_name": "Acme Platform",
  "created_at": "2026-01-01T00:00:00Z"
}
```

**Example:**

```sh
scribase org get acme
```

---

## Memberships

Members are subjects (user IDs or service account IDs from your OIDC provider)
with an assigned role.

### PUT /v1/organizations/{organization_id}/memberships

Add or update a member's role.

**Request body:**

```json
{ "subject": "user|abc123", "role": "developer" }
```

**Roles:**

| Role | Permissions |
|---|---|
| `owner` | Full control, including deleting the organization |
| `admin` | Manage projects and environments |
| `developer` | Create and manage environments |
| `viewer` | Read-only access |

**Headers required:** `Idempotency-Key`

**Example:**

```sh
scribase member put acme "user|abc123" developer
```

---

## Audit events

See [Audit Events](https://docs.scribase.com/docs/api/audit.md) for the organization audit log.