# Update API key

Updates name, permissions, or expiry for one community API key.

- Endpoint: `PUT https://api.returning.ai/v1/communities/{communityId}/api-keys/{apiKeyId}`
- Section: API keys / Community keys
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Retries: Retry timeouts after listing by `_id`.
- Guide: generated from the published specification
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/api-keys-community-api-keys/update-api-key

## Authentication

- Header: `Authorization: Bearer <API_KEY>`

Bearer community API key that can manage keys for this community. Keep it server-side.

## Behaviour

It does not rotate the secret. `data.key` is still returned.

**Workflow:** List keys → copy `_id` → `PUT` with the full intended `name`, `permissions`, and `expirePeriod` → prove one allowed and one forbidden call.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `communityId` | `string` | Yes | The unique identifier of the community (ObjectId) |
| `apiKeyId` | `string` | Yes | The unique identifier of the API key to update (ObjectId) |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | API key. (`Bearer <API_KEY>`) |
| `Content-Type` | `string` | Yes | Request body format. (`application/json`) |

### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | The name of the API key for identification (Min 1 chars) |
| `permissions` | `string[]` | No | Array of permissions to assign to the API key (Default `[]`) |
| `expirePeriod` | `number` | No | Expiration period in days (0 for no expiration) (Min 0) |
| `expireDate` | `string` | No | Specific expiration date for the API key (Date-time) |

### Watch for

- Update is not rotate. Create a replacement key, switch the integration, then delete the old `_id`.

### Example request

```bash
curl --request PUT \
  --url 'https://api.returning.ai/v1/communities/<communityId>/api-keys/<apiKeyId>' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated Slack Integration Key",
    "permissions": [
      "sendMessage",
      "replyMessage",
      "createUser",
      "manageUser",
      "getUserData",
      "getUserStats",
      "bulkUpdateUser",
      "userFields"
    ],
    "expirePeriod": 0,
    "expireDate": "2025-12-15T23:59:59.000Z"
  }'
```

### More examples

**Updated (200).** `message` is `Update API key success.` `data` includes `_id`, `communityId`, `name`, `key`, `permissions`, `expirePeriod`, `createdAt`, `updatedAt`.

Invalid permission enum values return the same `Create API key validation error.`-style enum `detail` as create.

Never paste live `key` values.

## Response

HTTP `200`. The secret does not change. List again and match `_id`. A key missing `leaderboard` still 403s `GET /v1/leaderboards` after this PUT unless you add that permission.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `meta` | `object` | - | - |
| `meta.status` | `string` | - | Response status |
| `meta.statusCode` | `number` | - | HTTP status code |
| `message` | `string` | - | Success message for the operation |
| `data` | `object` | - | - |
| `data._id` | `string` | - | The unique identifier of the API key |
| `data.name` | `string` | - | The updated name of the API key |
| `data.key` | `string` | - | The API key value (unchanged during update) |
| `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
  },
  "message": "Update API key success.",
  "data": {
    "_id": "675b9876fedc432109876543",
    "name": "Updated Slack Integration Key",
    "key": "<API_KEY>",
    "permissions": [
      "sendMessage",
      "replyMessage",
      "createUser",
      "manageUser",
      "getUserData",
      "getUserStats",
      "bulkUpdateUser",
      "userFields"
    ],
    "expirePeriod": 0,
    "expireDate": "2025-12-15T23:59:59.000Z",
    "updatedAt": "2024-12-15T15:45:22.789Z",
    "createdAt": "2024-12-15T10:30:45.123Z"
  }
}
```

## 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. |
| 409 | - | The request conflicts with an existing resource or immutable state, such as a duplicate slug/key/name or an already-processed record. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | - | Internal server error. |

**Retries:** Retry timeouts after listing by `_id`. Repeating the same PUT is a metadata overwrite, not a second secret.

## Next step

- [Delete API key](https://docs.returning.ai/api-reference/api-keys-community-api-keys/delete-api-key.md): `DELETE /v1/communities/{communityId}/api-keys/{apiKeyId}`. Revoke the old key only after the replacement is in use.