Create API key

Creates a new API key for a community. API keys can be used for authentication
and access control to community resources.

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:

Generates secure 64-character API key with SHA-256 hash

Supports optional expiration period or specific expiration date

Allows custom permissions assignment for fine-grained access control

Emits real-time event to community members

Validates all input parameters for security

What it is for: Creates a community API key with a controlled permission set.
How to use it: Send a POST request to /v1/communities/{communityId}/api-keys with the request body, query parameters, or multipart fields shown below. Authorization: Bearer <apiKey>. The key must be active, unexpired, scoped to the correct community, and include the permission required by this endpoint.
Successful response: HTTP 201. The body follows the endpoint schema; many integration endpoints wrap the useful payload under data with status and message.
Common error states:

400 invalid request body, query, ObjectId, pagination, file format, or missing required field.

401 missing, invalid, expired, or insufficient API key/token.

403 key is valid but cannot access this community/channel/user/resource, where supported by the service.

404 target resource, route, or community-scoped record was not found.

409 duplicate or conflicting state for create/update operations, where applicable.

500 unexpected Returning.AI service error.

curl --location 'https://api.returning.ai/v1/communities//api-keys' \ --header 'Content-Type: application/json' \ --data '{ "name": "Slack Integration API Key", "permissions": [ "sendMessage", "replyMessage", "createUser", "manageUser", "getUserData", "getUserStats", "bulkUpdateUser", "userFields" ], "expirePeriod": 0 }'

{ "meta": { "status": "success", "statusCode": 201 }, "message": "Create API key success.", "data": { "_id": "675b9876fedc432109876543", "name": "Slack Integration API Key", "key": "<apiKey>", "permissions": [ "sendMessage", "replyMessage", "createUser", "manageUser", "getUserData", "getUserStats", "bulkUpdateUser", "userFields" ], "expirePeriod": 0, "expireDate": "", "updatedAt": "2024-12-15T10:30:45.123Z", "createdAt": "2024-12-15T10:30:45.123Z" } }

Request

Responses