Getting Started

Create one scoped community API key, send it as a bearer credential, and make a /v1 read.

INFO

One authentication standard

Server-to-server integrations authenticate with Authorization: Bearer <COMMUNITY_API_KEY>. Password login and /auth/register are not mounted on https://api.returning.ai.

Make your first request

Create an API key

In the community admin, open Settings > Integration > API Keys. Create a key for this integration only.

Choose permissions

Grant only the permissions named on the endpoints you will call. User lookup needs getUserData. Messaging needs sendMessage / getMessages. Leaderboards need leaderboard.

Store the secret

Save the generated key in server-side secret storage. Key list responses can include raw key values, so treat those bodies as secret-bearing too.

Try a read request

A successful lookup returns 200 with code: USER_DATA_RETRIEVED. Use a member email from that community.

Community-scoped directory (no query string):

Permissions and security

Principle	What to do
Community scope	Use a key created for the community the integration should access.
Least privilege	Grant only the permissions named on the endpoints you call.
Expiration	Set an expiration that matches the integration's operating window.
Secret storage	Keep the key in server-side secret storage. Never ship it in browser, mobile, or widget frontend code.
Rotation	Create and test a replacement key before revoking the old key.

WARNING

Store the generated key securely

Treat the key as a password. Do not paste it into tickets, chat messages, screenshots, browser code, or public repositories. Public examples on this site use <COMMUNITY_API_KEY> only.

Authentication errors

HTTP	Meaning	What to do
`401`	The credential is missing, malformed, invalid, or expired.	Add, replace, or rotate the API key.
`403`	The credential is valid but lacks the required permission.	Add the permission documented on the endpoint. Example: `GET /v1/leaderboards` returns `AUTH_PERMISSION_REQUIRED` `leaderboard` when that bit is missing.
`404` `Route not found`	The path is not mounted on this gateway.	Use the replacement on the page (for example `POST /v1/users/info` instead of `GET /v1/users/{userId}`).

Next steps

User directory

Create, look up, filter, and manage members. Community list/get live beside Users.

Community API keys

List and rotate community keys. User-key routes are not mounted on this gateway.

Messages

Get, send, reply, react, then upload images as multipart.

Legacy routes

Make your first request#

Try a read request#

Permissions and security#

Authentication errors#

Next steps#

Make your first request

Try a read request

Permissions and security

Authentication errors

Next steps