Create API key
POST
https://sgtr-integration.returning.ai/apis/v1/communities/{communityId}/api-keys
API Keys/Community API Keys
What this endpoint does
key once in the same envelope later list/update/delete also return. Treat every management response as secret-bearing.INFO
name → POST a least-privilege key → store data.key in server-side secret storage → prove one allowed call → delete when rotating.Quick start
expirePeriod: 0 means no expiry. Replace <communityId> with the 24-character community ObjectId.Authentication and permission
Authorization: Bearer <COMMUNITY_API_KEY>. The managing key must belong to that community. Keep it server-side.Complete examples
message is Create API key success. Envelope { meta: { status: "success", statusCode: 201 }, message, data }.data includes _id, name, key, permissions, expirePeriod, createdAt, updatedAt.Create API key validation error. detail.name: API key name is required.detail.permissions lists the allowed enum. Community names include getUserData, sendMessage, leaderboard, appearance, getBulkUpdate. User-key names such as sendMessages are not valid here.key values into docs, tickets, or examples.Success and readback
201. Store data.key immediately. Read back with list and match _id or name. Update keeps the same key. Delete revokes it.CHECK
data.key is present, redact it in logs. Listing the same key later also returns key.Errors and recovery
| Status | When | Recovery |
|---|---|---|
400 name required | Missing name | Send a unique name. |
400 invalid enum | Unknown permission string | Use a community permission from the error detail. |
400 duplicate name | name already exists | Pick a new name or update the existing key. |
401 | Missing or invalid token | Add a valid community key. |
Retry safety
WARNING
name before posting the same body again. Duplicate names conflict; a second successful create with a new name is another secret.Gotchas
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.Next steps
Request
Path Params
Body Params application/json
Responses
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location 'https://sgtr-integration.returning.ai/apis/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
}'Response Response Example
201 - Success
{
"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"
}
}Modified at 2026-08-19 13:43:47