Update API key - Returning.AI

Updates an existing API key for a community. This endpoint allows modification of
API key properties such as name, permissions, and expiration settings.

Security Requirements:

Bearer token authentication required

Only community owners and administrators can access this endpoint

User must have either COMMUNITY_OWNER or COMMUNITY_ADMIN permissions for the specified community

Key Features:

Update API key name for better identification

Modify permissions array to control access levels

Adjust expiration period or specific expiration date

API key value remains unchanged and secure

Emits real-time event to community members

Validates all input parameters for security

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

communityId

string <objectId>

required

The unique identifier of the community

Example:

675a1234bcde567890123456

apiKeyId

string <objectId>

required

The unique identifier of the API key to update

Example:

675b9876fedc432109876543

Body Params application/json

name

string

required

The name of the API key for identification

>= 1 characters

Example:

Updated Slack Integration Key

permissions

array[string]

optional

Array of permissions to assign to the API key

Example:

["sendMessage","replyMessage","createUser","manageUser","getUserData","getUserStats","bulkUpdateUser","userFields"]

expirePeriod

number

optional

Expiration period in days (0 for no expiration)

>= 0

Example:

expireDate

string <date-time>

optional

Specific expiration date for the API key

Example:

2025-12-15T23:59:59.000Z

Examples

Update Slack integration keyUpdate webhook service permissionsExtend expiration period

{
    "name": "Updated Slack Integration Key",
    "permissions": [
        "sendMessage",
        "replyMessage",
        "createUser",
        "manageUser",
        "getUserData",
        "getUserStats",
        "bulkUpdateUser",
        "userFields"
    ],
    "expirePeriod": 0,
    "expireDate": "2025-12-15T23:59:59.000Z"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Update API key successful

Body

meta

object

optional

status

string

optional

Response status

statusCode

number

optional

HTTP status code

message

string

optional

Success message for the operation

data

object

optional

_id

string

optional

The unique identifier of the API key

name

string

optional

The updated name of the API key

key

string

optional

The API key value (unchanged during update)

permissions

array[string]

optional

Array of permissions assigned to the API key

expirePeriod

number

optional

Expiration period in days (0 for no expiration)

expireDate

string

optional

Specific expiration date for the API key

updatedAt

string <date-time>

optional

When the API key was last updated

createdAt

string <date-time>

optional

When the API key was created

Example

{
    "meta": {
        "status": "success",
        "statusCode": 200
    },
    "message": "Update API key success.",
    "data": {
        "_id": "675b9876fedc432109876543",
        "name": "Updated Slack Integration Key",
        "key": "8f3e4d5c6b7a9e2f1a4b7c8d5e9f2a6b3c7e8f1a4b5c9d2e6f8a1b4c7e9f2a5b8c",
        "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"
    }
}

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

🔴500Server Error