Returning.AIDevelopers
v1

API reference / API Keys / Community API Keys

.md

Read API keys

Lists community API keys for one community ObjectId.

Last updated 26 Sep 2026API v1

Method
GET
Path
https://api.returning.ai/v1/communities/{communityId}/api-keys
Retries
This GET does not create keys.

When to use this

Use it from server-side admin tooling to inspect names, permissions, and expiration.

Authentication#

Header
Authorization: Bearer <API_KEY>

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

Behaviour#

It does not rotate the secret. It is not a user-key list. The response includes the raw key value. Treat the body as secret-bearing.

Request#

Path parameters#

communityId#stringREQUIRED
The unique identifier of the community

RuleObjectId

Query parameters#

page#integerOPTIONAL
Page number for pagination

RuleMin 1; default 1

Eg1

limit#integerOPTIONAL
Number of API keys per page

RuleDefault 20; max 100

Eg20

Headers#

Authorization#stringREQUIRED
API key.

RuleBearer <API_KEY>

Watch for

  • User API key routes (/v1/users/apikeys, /v1/api-key-info) are not mounted on this gateway.
  • GET /v1/api-key-info is not a substitute for this list.
  • Permission enum names are community-key names (sendMessage, getUserData), not user-key names (sendMessages).
More examples and details

List (200). message is Get API keys success. Envelope { meta, message, data }. meta includes statusCode: 200, total, page, limit.

Each data[] item includes _id, communityId, name, key, permissions, expirePeriod, createdAt, updatedAt.

Limit too large (400). limit above 100 returns Get API keys error. with detail.limit: Number must be less than or equal to 100.

Treat names as synthetic. Never paste live key values into docs, tickets, or examples.

curl --request GET \
  --url 'https://api.returning.ai/v1/communities/<communityId>/api-keys?page=1&limit=20' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

HTTP 200. data is an array. This GET is the readback after create/update/delete: match _id or name.

expirePeriod: 0 means no expiry.

meta#object

Eg{ ... }

status#string
Response status

Eg"success"

statusCode#number
HTTP status code

Eg200

total#number
Total number of API keys

Eg5

page#number
Current page number

Eg1

limit#number
Number of items per page

Eg20

message#string
Success message for the operation

Eg"Read API keys 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 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)

Eg0

expireDate#string
Specific expiration date for the API key
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": 200,
    "total": 5,
    "page": 1,
    "limit": 20
  },
  "message": "Read API keys 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"
    },
    {
      "_id": "675c1122aabb334455667788",
      "name": "Payment Webhook Service",
      "key": "<API_KEY>",
      "permissions": [
        "sendMessage",
        "replyMessage",
        "createUser",
        "manageUser",
        "getUserData",
        "getUserStats",
        "bulkUpdateUser",
        "userFields"
      ],
      "expirePeriod": 365,
      "expireDate": "2025-12-15T23:59:59.000Z",
      "updatedAt": "2024-12-10T16:42:18.789Z",
      "createdAt": "2024-12-10T09:15:30.456Z"
    },
    {
      "_id": "675d2233ccdd445566778899",
      "name": "Development Testing Key",
      "key": "<API_KEY>",
      "permissions": [
        "sendMessage",
        "replyMessage",
        "createUser",
        "manageUser",
        "getUserData",
        "getUserStats",
        "bulkUpdateUser",
        "userFields"
      ],
      "expirePeriod": 30,
      "expireDate": "2025-01-14T23:59:59.000Z",
      "updatedAt": "2024-12-14T14:20:12.345Z",
      "createdAt": "2024-12-14T14:20:12.345Z"
    }
  ]
}

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 data01

404Fix the data
Resource not found.

Retry with backoff01

500Retry with backoff
Internal server error.
{
  "meta": {
    "status": "error",
    "statusCode": 400
  },
  "message": "Read API keys error.",
  "errors": {
    "page": "Page must be at least 1"
  }
}

Next step#

Create API keyPOST/v1/communities/{communityId}/api-keysCreate a least-privilege key, store the secret once, then prove one allowed and one forbidden call.