# Read API keys

Lists community API keys for one community ObjectId.

- Endpoint: `GET https://api.returning.ai/v1/communities/{communityId}/api-keys`
- Section: API keys / Community keys
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Retries: This GET does not create keys.
- Guide: generated from the published specification
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/api-keys-community-api-keys/read-api-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.

**Workflow:** Authenticate as a caller that can manage this community → `GET /v1/communities/{communityId}/api-keys` → match by `name` → store permissions, never logs of `data[].key`.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `communityId` | `string` | Yes | The unique identifier of the community (ObjectId) |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | No | Page number for pagination (Min 1; default `1`) |
| `limit` | `integer` | No | Number of API keys per page (Default 20; max 100) |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | API key. (`Bearer <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`).

### Example request

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

### More examples

**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.

## 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.

**Secret-bearing read:** If `data[].key` is present, redact it in logs. Listing is enough to leak every community key the caller can see.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `meta` | `object` | - | - |
| `meta.status` | `string` | - | Response status |
| `meta.statusCode` | `number` | - | HTTP status code |
| `meta.total` | `number` | - | Total number of API keys |
| `meta.page` | `number` | - | Current page number |
| `meta.limit` | `number` | - | Number of items per page |
| `message` | `string` | - | Success message for the operation |
| `data` | `object[]` | - | - |
| `data._id` | `string` | - | The unique identifier of the API key |
| `data.name` | `string` | - | The name of the API key |
| `data.key` | `string` | - | The API key value |
| `data.permissions` | `string[]` | - | Array of permissions assigned to the API key |
| `data.expirePeriod` | `number` | - | Expiration period in days (0 for no expiration) |
| `data.expireDate` | `string` | - | Specific expiration date for the API key |
| `data.updatedAt` | `string` | - | When the API key was last updated (Date-time) |
| `data.createdAt` | `string` | - | When the API key was created (Date-time) |

### Example response (200)

```json
{
  "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 request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | Bad request - Invalid input. |
| 401 | - | Unauthorized - Invalid or missing authentication. |
| 403 | - | Forbidden - Insufficient permissions. |

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 404 | - | Resource not found. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | - | 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.

## Next step

- [Create API key](https://docs.returning.ai/api-reference/api-keys-community-api-keys/create-api-key.md): `POST /v1/communities/{communityId}/api-keys`. Create a least-privilege key, store the secret once, then prove one allowed and one forbidden call.