# Invitations

5 endpoints.

## List my pending invitations

```http
GET https://orbitwrite.com/api/v1/invitations
```

Returns the signed-in user's pending workspace invitations, enriched with the inviting workspace's logo and slug. Better Auth's own `listUserInvitations` joins the organization but only maps `organizationName` through, dropping `logo`/`slug` — and the invitee isn't a member yet, so the client's org list can't supply the logo either. The join here lets the user menu render the real workspace avatar instead of just an initial.

**Authentication:** session cookie.

### Responses

#### 200

The user's pending invitations

- `invitations` (MyInvitation[], required)
  - `id` (string, required)
  - `organizationId` (string, required)
  - `organizationName` (string, required)
  - `organizationSlug` (string, required)
  - `organizationLogo` (string | null, required)
  - `role` (string | null, required)

#### 401

Not signed in

- `error` (string, required)
- `issues` (any[], optional)

#### 403

Not a member of the organization

- `error` (string, required)
- `issues` (any[], optional)

## Invite someone to a workspace

```http
POST https://orbitwrite.com/api/v1/invitations
```

Creates a Better Auth organization invitation and emails the invitee an accept link. Owner/admin only. If the invitee already has an account they also get an in-app notification.

**Authentication:** session cookie.

### Request body (`application/json`)

- `organizationId` (string, required)
- `email` (string, required)
- `role` (string, optional, one of `admin`, `manager`, `member`)

### Responses

#### 200

The invitation was created and the email sent

- `ok` (boolean, required, one of `true`)
- `invitationId` (string, required)

#### 400

Invalid request

- `error` (string, required)
- `issues` (any[], optional)

#### 401

Not signed in

- `error` (string, required)
- `issues` (any[], optional)

#### 403

Not a member of the organization

- `error` (string, required)
- `issues` (any[], optional)

## List a workspace's pending invitations

```http
GET https://orbitwrite.com/api/v1/invitations/workspace
```

Returns the organization's pending (not yet accepted/cancelled) invitations, oldest first. Owner/admin only — the same gate the Members settings page applies before showing them.

**Authentication:** session cookie.

### Query parameters

- `organizationId` (string, required)

### Responses

#### 200

The workspace's pending invitations

- `invitations` (WorkspaceInvitation[], required)
  - `id` (string, required)
  - `email` (string, required)
  - `role` (string | null, required)
  - `expiresAt` (string, required) — ISO 8601 timestamp

#### 400

Invalid request

- `error` (string, required)
- `issues` (any[], optional)

#### 401

Not signed in

- `error` (string, required)
- `issues` (any[], optional)

#### 403

Not a member of the organization

- `error` (string, required)
- `issues` (any[], optional)

## Accept an invitation

```http
POST https://orbitwrite.com/api/v1/invitations/{id}/accept
```

Accepts one of the signed-in user's pending invitations (Better Auth creates the membership) and tells the inviter. Returns the joined workspace so the client can navigate into it. The email accept link uses the /accept-invitation/:id web route instead — that flow also has to create a fallback personal workspace and redirect.

**Authentication:** session cookie.

### Path parameters

- `id` (string, required)

### Responses

#### 200

The invitation was accepted

- `ok` (boolean, required, one of `true`)
- `organization` (object, required)
  - `id` (string, required)
  - `name` (string, required)
  - `slug` (string, required)

#### 401

Not signed in

- `error` (string, required)
- `issues` (any[], optional)

#### 403

Not a member of the organization

- `error` (string, required)
- `issues` (any[], optional)

#### 404

The resource does not exist

- `error` (string, required)
- `issues` (any[], optional)

## Revoke a pending invitation

```http
DELETE https://orbitwrite.com/api/v1/invitations/{id}
```

Cancels a pending invitation (Better Auth marks it cancelled — the accept link stops working). Owner/admin only.

**Authentication:** session cookie.

### Path parameters

- `id` (string, required)

### Responses

#### 200

The invitation was revoked

- `ok` (boolean, required, one of `true`)

#### 401

Not signed in

- `error` (string, required)
- `issues` (any[], optional)

#### 403

Not a member of the organization

- `error` (string, required)
- `issues` (any[], optional)

#### 404

The resource does not exist

- `error` (string, required)
- `issues` (any[], optional)