Create API key - Returning.AI

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

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

Body Params application/json

name

string

required

The name of the API key for identification

>= 1 characters

Example:

Slack Integration API 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:

365

expireDate

string <date-time>

optional

Specific expiration date for the API key

Example:

2024-12-31T23:59:59Z

Examples

Slack integration API keyWebhook service API keyDevelopment testing key

{
    "name": "Slack Integration API Key",
    "permissions": [
        "sendMessage",
        "replyMessage",
        "createUser",
        "manageUser",
        "getUserData",
        "getUserStats",
        "bulkUpdateUser",
        "userFields"
    ],
    "expirePeriod": 0
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢201Created

application/json

Create 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 name of the API key

key

string

optional

The generated API key value

permissions

array[string]

optional

Array of permissions assigned to the API key

expirePeriod

number | null

optional

Expiration period in days (0 for no expiration)

expireDate

string <date-time> | null

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": 201
    },
    "message": "Create API key success.",
    "data": {
        "_id": "675b9876fedc432109876543",
        "name": "Slack Integration API Key",
        "key": "8f3e4d5c6b7a9e2f1a4b7c8d5e9f2a6b3c7e8f1a4b5c9d2e6f8a1b4c7e9f2a5b8c",
        "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"
    }
}

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

🔴500Server Error