Returning.AIDevelopers
v1

API reference / API Keys / Community API Keys

.md

Create API key

Creates a community API key for one community ObjectId.

Last updated 26 Sep 2026API v1

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

Authentication#

Header
Authorization: Bearer <API_KEY>

The managing key must belong to that community. Keep it server-side.

Behaviour#

The create body returns the raw key once in the same envelope later list/update/delete also return. Treat every management response as secret-bearing.

It does not create user API keys. Those routes are not mounted on this gateway.

Request#

Path parameters#

communityId#stringREQUIRED
The unique identifier of the community

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"Slack Integration API 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"2024-12-31T23:59:59Z"

Watch for

  • List/update/delete also return key. The OpenAPI text that says list keys are masked is wrong on https://api.returning.ai.
  • GET /v1/users/apikeys and GET /v1/api-key-info 404.
  • Widget embed keys are a different credential.
More examples and details

Created (201). message is Create API key success. Envelope { meta: { status: "success", statusCode: 201 }, message, data }.

data includes _id, name, key, permissions, expirePeriod, createdAt, updatedAt.

Missing name (400). Create API key validation error. detail.name: API key name is required.

Invalid permission (400). detail.permissions lists the allowed enum. Community names include getUserData, sendMessage, leaderboard, appearance, getBulkUpdate. User-key names such as sendMessages are not valid here.

Never paste live key values into docs, tickets, or examples.

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

Response#

HTTP 201. Store data.key immediately. Read back with list and match _id or name. Update keeps the same key. Delete revokes it.

meta#object

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

status#string
Response status

Eg"success"

statusCode#number
HTTP status code

Eg201

message#string
Success message for the operation

Eg"Create API key success."

data#object

Eg{ ... }

_id#string
The unique identifier of the API key

Eg"675b9876fedc432109876543"

name#string
The name of the API key

Eg"Slack Integration API Key"

key#string
The generated API key value

Eg"<API_KEY>"

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

Eg[ ... ]

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

RuleNullable

Eg0

expireDate#string
Specific expiration date for the API key

RuleDate-time; nullable

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-12-15T10:30:45.123Z"

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

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": "Create API key error.",
  "detail": {
    "name": "API key name is required"
  }
}

Next step#

Read community API keysGET/v1/communities/{communityId}/api-keysConfirm the new _id and permissions. Treat data[].key as secret-bearing.