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

# Organizations API

> Read organization details, manage members, and configure organization settings via the Pwnbook API.

## Endpoints

| Method   | Path                                            | Description                  |
| -------- | ----------------------------------------------- | ---------------------------- |
| `GET`    | `/api/v1/organizations/current`                 | Get the current organization |
| `PATCH`  | `/api/v1/organizations/current`                 | Update organization settings |
| `GET`    | `/api/v1/organizations/current/members`         | List organization members    |
| `POST`   | `/api/v1/organizations/current/members/invite`  | Invite a new member          |
| `DELETE` | `/api/v1/organizations/current/members/:userId` | Remove a member              |
| `PATCH`  | `/api/v1/organizations/current/members/:userId` | Update a member's role       |

## Get current organization

Returns the organization associated with the API key.

**Required scope:** `organizations:read`

```http theme={null}
GET /api/v1/organizations/current
Authorization: Bearer YOUR_API_KEY
```

### Example request

```bash theme={null}
curl "https://your-pwnbook-domain.com/api/v1/organizations/current" \
  -H "Authorization: Bearer pwbk_live_abc123..."
```

### Example response

```json theme={null}
{
  "data": {
    "id": "org_01j9k2m3n4p5q6r7s8t9",
    "name": "Redteam Security LLC",
    "slug": "redteam-security",
    "plan": "business",
    "memberCount": 8,
    "createdAt": "2024-06-01T00:00:00.000Z",
    "settings": {
      "requireTwoFactor": true,
      "domainAutoJoin": false,
      "ssoEnabled": false
    }
  }
}
```

## Update organization

Updates organization settings.

**Required scope:** `organizations:write`

```http theme={null}
PATCH /api/v1/organizations/current
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

### Request body

| Field  | Type   | Required | Description               |
| ------ | ------ | -------- | ------------------------- |
| `name` | string | No       | Organization display name |

### Example request

```bash theme={null}
curl -X PATCH "https://your-pwnbook-domain.com/api/v1/organizations/current" \
  -H "Authorization: Bearer pwbk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Redteam Security Group LLC"
  }'
```

### Example response

```json theme={null}
{
  "data": {
    "id": "org_01j9k2m3n4p5q6r7s8t9",
    "name": "Redteam Security Group LLC",
    "slug": "redteam-security",
    "updatedAt": "2025-03-01T12:00:00.000Z"
  }
}
```

## List members

Returns all members of the organization.

**Required scope:** `organizations:read`

```http theme={null}
GET /api/v1/organizations/current/members
Authorization: Bearer YOUR_API_KEY
```

### Query parameters

| Parameter | Type    | Description                                |
| --------- | ------- | ------------------------------------------ |
| `role`    | string  | Filter by role: `owner`, `admin`, `member` |
| `page`    | integer | Page number (default: 1)                   |
| `perPage` | integer | Results per page (default: 20, max: 100)   |

### Example request

```bash theme={null}
curl "https://your-pwnbook-domain.com/api/v1/organizations/current/members" \
  -H "Authorization: Bearer pwbk_live_abc123..."
```

### Example response

```json theme={null}
{
  "data": [
    {
      "id": "usr_01j9k2m3n4p5q6r7s8t9",
      "name": "Alice Chen",
      "email": "alice@redteamsecurity.com",
      "role": "owner",
      "joinedAt": "2024-06-01T00:00:00.000Z",
      "lastSeenAt": "2025-03-01T09:30:00.000Z"
    },
    {
      "id": "usr_02j9k2m3n4p5q6r7s8t9",
      "name": "Bob Martinez",
      "email": "bob@redteamsecurity.com",
      "role": "member",
      "joinedAt": "2024-07-15T00:00:00.000Z",
      "lastSeenAt": "2025-02-28T16:45:00.000Z"
    }
  ],
  "meta": {
    "total": 8,
    "page": 1,
    "perPage": 20,
    "totalPages": 1
  }
}
```

## Invite a member

Sends an invitation email to a new member.

**Required scope:** `organizations:write`

```http theme={null}
POST /api/v1/organizations/current/members/invite
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

### Request body

| Field   | Type   | Required | Description                         |
| ------- | ------ | -------- | ----------------------------------- |
| `email` | string | Yes      | Email address to invite             |
| `role`  | string | Yes      | Role to assign: `admin` or `member` |

### Example request

```bash theme={null}
curl -X POST "https://your-pwnbook-domain.com/api/v1/organizations/current/members/invite" \
  -H "Authorization: Bearer pwbk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carol@redteamsecurity.com",
    "role": "member"
  }'
```

### Example response

```json theme={null}
{
  "data": {
    "id": "inv_01j9k2m3n4p5q6r7s8t9",
    "email": "carol@redteamsecurity.com",
    "role": "member",
    "status": "pending",
    "expiresAt": "2025-03-08T12:00:00.000Z",
    "createdAt": "2025-03-01T12:00:00.000Z"
  }
}
```

The invitee receives an email with a link to accept the invitation. Invitations expire after 7 days.

## Update a member's role

Changes the role of an existing organization member.

**Required scope:** `organizations:write`

```http theme={null}
PATCH /api/v1/organizations/current/members/:userId
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

### Request body

| Field  | Type   | Required | Description                   |
| ------ | ------ | -------- | ----------------------------- |
| `role` | string | Yes      | New role: `admin` or `member` |

### Example request

```bash theme={null}
curl -X PATCH "https://your-pwnbook-domain.com/api/v1/organizations/current/members/usr_02j9k2m3n4p5q6r7s8t9" \
  -H "Authorization: Bearer pwbk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'
```

### Example response

```json theme={null}
{
  "data": {
    "id": "usr_02j9k2m3n4p5q6r7s8t9",
    "role": "admin",
    "updatedAt": "2025-03-01T12:30:00.000Z"
  }
}
```

<Note>You cannot change the role of an Owner via the API. Ownership transfer must be done through the Pwnbook web UI by the current owner.</Note>

## Remove a member

Removes a member from the organization. The user's account is not deleted.

**Required scope:** `organizations:write`

```http theme={null}
DELETE /api/v1/organizations/current/members/:userId
Authorization: Bearer YOUR_API_KEY
```

### Example request

```bash theme={null}
curl -X DELETE "https://your-pwnbook-domain.com/api/v1/organizations/current/members/usr_02j9k2m3n4p5q6r7s8t9" \
  -H "Authorization: Bearer pwbk_live_abc123..."
```

### Example response

```json theme={null}
{
  "data": {
    "removed": true,
    "userId": "usr_02j9k2m3n4p5q6r7s8t9"
  }
}
```

<Warning>Removing a member immediately revokes their access to the organization. This action takes effect instantly.</Warning>