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

# Database invitations API: list, resend, revoke

> List, resend and revoke DBHost database invitations for people without an account. Needs a full-account API key; invitations last 7 days.

When you [add a member](/api-reference/collaboration/members#add-a-member)
whose email does not belong to a DBHost user, DBHost emails an invitation
instead. These routes let you inspect, resend and revoke those invitations.
There is no separate create route.

* These routes require a **full-account** API key. A selected-database key
  receives `403 KEY_SCOPE_DENIED`. See [API keys](/dashboard/api-keys).
* The key acts as the account owner, so only databases you own are visible.
* API access requires a Pro or Business plan.

An invitation is valid for seven days. Statuses are `pending`, `accepted`,
`revoked` and `expired`. Only `pending` invitations can be resent or revoked.

## List invitations

`GET /api/v1/databases/{id}/invitations`

Returns the invitations recorded for the database. Before reading, DBHost
marks pending invitations whose `expiresAt` has passed as `expired`.

```http theme={null}
GET /api/v1/databases/{id}/invitations
Authorization: Bearer <api-key>
```

```json 200 OK theme={null}
{
  "data": [
    {
      "id": "b2c3d4e5-0000-4000-8000-000000000002",
      "email": "new@example.com",
      "role": "viewer",
      "status": "pending",
      "expiresAt": "2026-10-21T09:00:00.000Z",
      "createdAt": "2026-10-14T09:00:00.000Z"
    }
  ]
}
```

The list can include invitations in every status, not only `pending`. Filter
on `status` if you need open invitations only.

## Resend an invitation

`POST /api/v1/databases/{id}/invitations/{invitationId}/resend`

Sends a new invitation email for a pending invitation and resets its expiry to
seven days from now. The invitation keeps the same `id`. DBHost then tries to
revoke the link in the previous email; if that revocation fails, the old link
can keep working until it expires. No request body is needed.

```http theme={null}
POST /api/v1/databases/{id}/invitations/{invitationId}/resend
Authorization: Bearer <api-key>
```

```json 200 OK theme={null}
{
  "message": "Database invitation resent.",
  "data": {
    "id": "b2c3d4e5-0000-4000-8000-000000000002",
    "databaseId": "550e8400-e29b-41d4-a716-446655440000",
    "normalizedEmail": "new@example.com",
    "role": "viewer",
    "invitedByUserId": "<user-id>",
    "clerkInvitationId": "<delivery-id>",
    "status": "pending",
    "expiresAt": "2026-10-28T09:00:00.000Z",
    "acceptedByUserId": null,
    "acceptedAt": null,
    "revokedAt": null,
    "createdAt": "2026-10-14T09:00:00.000Z",
    "updatedAt": "2026-10-21T09:00:00.000Z"
  }
}
```

## Revoke an invitation

`DELETE /api/v1/databases/{id}/invitations/{invitationId}`

Revokes a pending invitation so its link can no longer be used. Returns
`204 No Content` with an empty body. The invitation stays in the list with
status `revoked`.

```http theme={null}
DELETE /api/v1/databases/{id}/invitations/{invitationId}
Authorization: Bearer <api-key>
```

All changes are recorded in the database's activity log.

## Errors

| Status | Code | Description |
| - | - | - |
| 401 | `UNAUTHORIZED` | Missing or invalid API key |
| 403 | `PLAN_API_ACCESS_REQUIRED` | The account is not on Pro or Business |
| 403 | `KEY_SCOPE_DENIED` | The key does not have full account access |
| 404 | `DATABASE_NOT_FOUND` | Database does not exist or is not owned by this account |
| 404 | `INVITATION_NOT_FOUND` | No pending invitation with this ID on this database |
| 409 | `DATABASE_LIFECYCLE_CONFLICT` | The database is being deleted (resend only) |
| 409 | `DATABASE_BUSY` | Another change held the database for the whole wait (resend only); retry after `Retry-After` seconds |
| 429 | `RATE_LIMITED` | Too many requests; retry after `Retry-After` seconds |
| 502 | `INVITATION_DELIVERY_FAILED` | The new invitation email could not be sent; the existing invitation is unchanged |
| 502 | `INVITATION_REVOKE_FAILED` | The invitation could not be revoked; retry |

The CLI equivalents are `dbhost invitations list <database-id>` and
`dbhost invitations resend|revoke <database-id> <invitation-id>`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.