API reference / API Keys / Community API Keys

Read API keys

Lists community API keys for one community ObjectId.

Last updated 28 Oct 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.

Retries

This GET does not create keys. Retry timeouts with bounded backoff. Repeating the list does not rotate secrets, but it does re-expose them in the body.

{
  "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.