Returning.AIDevelopers
v1

API reference / API Keys / Community API Keys

.md

Update API key

Updates name, permissions, or expiry for one community API key.

Last updated 26 Sep 2026API v1

Method
PUT
Path
https://api.returning.ai/v1/communities/{communityId}/api-keys/{apiKeyId}
Retries
Retry timeouts after listing by _id.

Authentication#

Header
Authorization: Bearer <API_KEY>

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

Behaviour#

It does not rotate the secret. data.key is still returned.

Request#

Path parameters#

communityId#stringREQUIRED
The unique identifier of the community

RuleObjectId

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

RuleObjectId

Headers#

Authorization#stringREQUIRED
API key.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

name#stringREQUIRED
The name of the API key for identification

RuleMin 1 chars

Eg"Updated Slack Integration Key"

permissions#string[]OPTIONAL
Array of permissions to assign to the API key

RuleDefault []

Eg[ ... ]

expirePeriod#numberOPTIONAL
Expiration period in days (0 for no expiration)

RuleMin 0

Eg0

expireDate#stringOPTIONAL
Specific expiration date for the API key

RuleDate-time

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

Watch for

  • Update is not rotate. Create a replacement key, switch the integration, then delete the old _id.
More examples and details

Updated (200). message is Update API key success. data includes _id, communityId, name, key, permissions, expirePeriod, createdAt, updatedAt.

Invalid permission enum values return the same Create API key validation error.-style enum detail as create.

Never paste live key values.

curl --request PUT \
  --url 'https://api.returning.ai/v1/communities/<communityId>/api-keys/<apiKeyId>' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated Slack Integration Key",
    "permissions": [
      "sendMessage",
      "replyMessage",
      "createUser",
      "manageUser",
      "getUserData",
      "getUserStats",
      "bulkUpdateUser",
      "userFields"
    ],
    "expirePeriod": 0,
    "expireDate": "2025-12-15T23:59:59.000Z"
  }'

Response#

HTTP 200. The secret does not change. List again and match _id. A key missing leaderboard still 403s GET /v1/leaderboards after this PUT unless you add that permission.

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"Update API key success."

data#object

Eg{ ... }

_id#string
The unique identifier of the API key

Eg"675b9876fedc432109876543"

name#string
The updated name of the API key

Eg"Updated Slack Integration Key"

key#string
The API key value (unchanged during update)

Eg"<API_KEY>"

permissions#string[]
Array of permissions assigned to the API key

Eg[ ... ]

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

Eg0

expireDate#string
Specific expiration date for the API key

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

updatedAt#string
When the API key was last updated

RuleDate-time

Eg"2024-12-15T15:45:22.789Z"

createdAt#string
When the API key was created

RuleDate-time

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

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

Errors#

Fix the request03

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

Fix the data02

404Fix the data
Resource not found.
409Fix the data
The request conflicts with an existing resource or immutable state, such as a duplicate slug/key/name or an already-processed record.

Retry with backoff01

500Retry with backoff
Internal server error.
{
  "meta": {
    "status": "error",
    "statusCode": 400
  },
  "message": "Update API key error.",
  "errors": {
    "name": "API key name cannot be empty"
  }
}

Next step#

Delete API keyDELETE/v1/communities/{communityId}/api-keys/{apiKeyId}Revoke the old key only after the replacement is in use.