Returning.AIDevelopers
v1

API reference / API Keys / Community API Keys

.md

Delete API key

Revokes one community API key by ObjectId.

Last updated 26 Sep 2026API v1

Method
DELETE
Path
https://api.returning.ai/v1/communities/{communityId}/api-keys/{apiKeyId}
Retries
A timeout can hide a successful revoke.

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.

Request#

Path parameters#

communityId#stringREQUIRED
The unique identifier of the community

RuleObjectId

apiKeyId#stringREQUIRED
The unique identifier of the API key to delete

RuleObjectId

Headers#

Authorization#stringREQUIRED
API key.

RuleBearer <API_KEY>

Watch for

  • Delete returns the secret in the body. Redact logs.
  • User API key delete routes are not mounted.
More examples and details

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.

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

Response#

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

meta#object

Eg{"status": "success", "statusCode": 200}

status#string
Response status

Eg"success"

statusCode#number
HTTP status code

Eg200

message#string
Success message for the operation

Eg"Delete API key success."

data#object

Eg{ ... }

_id#string
The unique identifier of the deleted API key

Eg"675b9876fedc432109876543"

name#string
The name of the deleted API key

Eg"Slack Integration API Key"

key#string
The API key value (partially masked for security)

Eg"<API_KEY>"

permissions#string[]
Array of permissions that were granted to the API key

Eg[ ... ]

expirePeriod#number
The expiration period in days (0 for no expiration)

Eg365

expireDate#string
The expiration date of the API key

RuleDate-time

Eg"2025-12-15T23:59:59.000Z"

updatedAt#string
When the API key was last updated

RuleDate-time

Eg"2024-12-15T10:30:45.123Z"

createdAt#string
When the API key was created

RuleDate-time

Eg"2024-01-15T09:15:22.456Z"

{
  "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 request03

400Fix the request
Bad request - Invalid input parameters.
401Fix the request
Unauthorized - Invalid or missing authentication.
403Fix the request
Forbidden - Insufficient permissions.

Fix the data01

404Fix the data
API key not found.

Retry with backoff01

500Retry with backoff
Internal server error.
{
  "meta": {
    "status": "error",
    "statusCode": 400
  },
  "message": "Delete API key error.",
  "errors": {
    "communityId": "Community ID must be a valid ObjectId"
  }
}

Next step#

API key lifecycleCreate, prove, switch, then delete. Never ship community keys in widget frontend code.