API key lifecycle

Create, list, update, and revoke community API keys. Use a managing key from server-side admin tooling, then hand a least-privilege key to each integration.

WARNING

List, create, update, and delete responses can include the raw key. Treat every management response as secret-bearing.

Community keys

GET /v1/communities/{communityId}/api-keys — 200 Get API keys success. data[].key is present.

POST /v1/communities/{communityId}/api-keys — 201 on create. Store data.key once.

PUT and DELETE on /v1/communities/{communityId}/api-keys/{apiKeyId}.

limit must be <= 100. Duplicate name conflicts. Invalid permission enum values return 400.

Not mounted

These routes 404 on https://api.returning.ai:

GET/POST /v1/users/apikeys

GET /v1/api-key-info

User-scoped update/delete paths

Widget embed keys are a different credential. See Widgets.

Permission names

Community keys use names such as getUserData, sendMessage, replyMessage, getMessages, createUser, manageUser, bulkUpdateUser, getBulkUpdate, getStreakLogs, customerSuccess, leaderboard.

User-key names (sendMessages, replyMessages) are not valid on community keys.

A key can list other keys without leaderboard. GET /v1/leaderboards still returns 403 until that permission is granted.

Rotate without an outage

Create a replacement with the same permissions.

Prove the replacement on one read.

Switch the integration secret.

Delete the old key.

Confirm the old _id is gone from the list.

Next endpoints

Community keys#

Not mounted#

Permission names#

Rotate without an outage#

Next endpoints#

Community keys

Not mounted

Permission names

Rotate without an outage

Next endpoints