# Delete API key

Revokes one community API key by ObjectId.

- Endpoint: `DELETE https://api.returning.ai/v1/communities/{communityId}/api-keys/{apiKeyId}`
- Section: API keys / Community keys
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Retries: A timeout can hide a successful revoke.
- Guide: generated from the published specification
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/api-keys-community-api-keys/delete-api-key

## Authentication

- Header: `Authorization: Bearer <API_KEY>`

Bearer community API key that can manage keys for this community. Keep it server-side.

## Behaviour

The delete response still includes `data.key`. Treat it as secret-bearing.

**Workflow:** Create and prove a replacement → switch the integration secret → `DELETE` the old `_id` → list and confirm the `_id` is gone.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `communityId` | `string` | Yes | The unique identifier of the community (ObjectId) |
| `apiKeyId` | `string` | Yes | The unique identifier of the API key to delete (ObjectId) |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | API key. (`Bearer <API_KEY>`) |

### Watch for

- Delete returns the secret in the body. Redact logs.
- User API key delete routes are not mounted.

### Example request

```bash
curl --request DELETE \
  --url 'https://api.returning.ai/v1/communities/<communityId>/api-keys/<apiKeyId>' \
  --header 'Authorization: Bearer <API_KEY>'
```

### More examples

**Deleted (200).** `message` is `Delete API key success.` Envelope includes `data._id`, `name`, `key`, and `permissions` of the revoked key.

Do not delete the managing key you are using until a replacement exists.

## Response

HTTP `200`. List community keys and confirm the `_id` is absent. Calls with the revoked secret should fail authentication.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `meta` | `object` | - | - |
| `meta.status` | `string` | - | Response status |
| `meta.statusCode` | `number` | - | HTTP status code |
| `message` | `string` | - | Success message for the operation |
| `data` | `object` | - | - |
| `data._id` | `string` | - | The unique identifier of the deleted API key |
| `data.name` | `string` | - | The name of the deleted API key |
| `data.key` | `string` | - | The API key value (partially masked for security) |
| `data.permissions` | `string[]` | - | Array of permissions that were granted to the API key |
| `data.expirePeriod` | `number` | - | The expiration period in days (0 for no expiration) |
| `data.expireDate` | `string` | - | The expiration date of the API key (Date-time) |
| `data.updatedAt` | `string` | - | When the API key was last updated (Date-time) |
| `data.createdAt` | `string` | - | When the API key was created (Date-time) |

### Example response (200)

```json
{
  "meta": {
    "status": "success",
    "statusCode": 200
  },
  "message": "Delete API key success.",
  "data": {
    "_id": "675b9876fedc432109876543",
    "name": "Slack Integration API Key",
    "key": "<API_KEY>",
    "permissions": [
      "sendMessage",
      "replyMessage",
      "createUser",
      "manageUser",
      "getUserData",
      "getUserStats",
      "bulkUpdateUser",
      "userFields"
    ],
    "expirePeriod": 365,
    "expireDate": "2025-12-15T23:59:59.000Z",
    "updatedAt": "2024-12-15T10:30:45.123Z",
    "createdAt": "2024-01-15T09:15:22.456Z"
  }
}
```

## Errors

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | Bad request - Invalid input parameters. |
| 401 | - | Unauthorized - Invalid or missing authentication. |
| 403 | - | Forbidden - Insufficient permissions. |

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 404 | - | API key not found. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | - | Internal server error. |

**Retries:** A timeout can hide a successful revoke. List by `_id` before deleting again. Do not retry blindly against a key you still need.

## Next step

- [API key lifecycle](https://dev.returning.ai/api-keys/overview): Create, prove, switch, then delete. Never ship community keys in widget frontend code.