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

# Revoke an Invitation

> Cancel an organization invitation and take back everything it granted.

Revoking is not just cancelling an email. Because an invitation provisions the person the moment it is sent, they may already be in workspaces and carrying groups and grants, so revoking takes all of it back.

> [!WARNING]
>
> Revoking removes the invitee from **every workspace** the invitation placed them in, with **every grant on all three permission axes** and every group membership. If the invitation was the only reason that person existed in Nekt, the account is deleted too. This cannot be undone: re-inviting them starts from nothing.

## The path parameter is the id

The URL segment is named `token`, but the value is the invitation's **`id`**, the field you get from [List Invitations](https://docs.nekt.com/platform-api/invitations/organization/list.md). Passing the invitation token instead returns `404`.

```bash theme={null}
curl --request DELETE \
  --url https://api.nekt.ai/api/v1/organization/invitations/c1f0a9d4-5b62-4e18-9a73-2d8e4f6b0c51/ \
  --header "x-api-key: YOUR_API_KEY"
```

## Response

`200`, with a confirmation body.

```json theme={null}
{ "detail": "The invitation has been revoked." }
```

## Revoke versus letting it lapse

These are different, and the difference is the access:

| | Link works | Workspaces, groups, and grants | Appears in the member list |
| - | - | - | - |
| **Expired** | No | Kept | Yes, as pending |
| **Revoked** | No | Removed | No |

An expired invitation is a pause: resend it and the person picks up exactly where you left them. A revoked one is a decision. Revoke when somebody is not joining; let one lapse when they are simply slow.

## Clean up invitations nobody answered

```python theme={null}
from datetime import datetime, timedelta, timezone

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.nekt.ai"
GIVE_UP_AFTER_DAYS = 90

headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}
cutoff = datetime.now(timezone.utc) - timedelta(days=GIVE_UP_AFTER_DAYS)

invitations = requests.get(f"{BASE_URL}/api/v1/organization/invitations/", headers=headers).json()

for invitation in invitations:
    sent_at = datetime.fromisoformat(invitation["sent_at"].replace("Z", "+00:00"))
    if sent_at < cutoff:
        # Takes back their workspaces, groups, and grants as well as the invitation.
        requests.delete(
            f"{BASE_URL}/api/v1/organization/invitations/{invitation['id']}/",
            headers=headers,
        )
```

## Errors

| Status | When |
| - | - |
| `400` | The invitation has already been accepted. Accepted people are members now; remove them from [Members](https://docs.nekt.com/organizations/members.md) instead. |
| `403` | Your API key was created by an organization member. Revoking requires the key of an organization owner or admin. |
| `404` | No invitation with that **id** in your organization; check you are not passing the token. |

## Related

* [Onboarding flow](https://docs.nekt.com/platform-api/invitations/overview.md): what an invitation carries.
* [List Invitations](https://docs.nekt.com/platform-api/invitations/organization/list.md): where the `id` comes from.
* [Revoke a Workspace Invitation](https://docs.nekt.com/platform-api/invitations/workspace/revoke.md): for workspace admins, limited to invitations that stay inside their workspace.


## OpenAPI

````yaml DELETE /api/v1/organization/invitations/{token}/
openapi: 3.0.3
info:
  title: Nekt API
  version: v1
  description: Nekt API Documentation
  contact:
    email: support@nekt.ai
servers:
  - url: https://api.nekt.ai
security: []
paths:
  /api/v1/organization/invitations/{token}/:
    delete:
      tags:
        - v1
      description: >-
        The organization's invitations. Each names the user it created, pending
        in the organization

        until they accept, and the workspace it was issued in (null for an
        invitation to the

        organization). `created_by`, `user` and `workspace` are ids;
        `expand[]=created_by`,

        `expand[]=user` and `expand[]=workspace` return the objects. Inviting
        can also place the invitee

        in workspaces right away (`workspaces`), each at a role; the invitation
        still belongs to the

        organization.
      operationId: v1_organization_invitations_destroy
      parameters:
        - in: path
          name: token
          schema:
            type: string
            format: uuid
          description: >-
            The invitation's `id`. Despite the name, this is not the invitation
            token.
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitationRevoked'
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    InvitationRevoked:
      type: object
      properties:
        detail:
          type: string
      required:
        - detail
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API Key authentication. Format: ''x-api-key: api_key'''

````

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