Reecall
Getting Started

Authentication

Use a Reecall API key to authenticate requests from your backend. Send it as a Bearer token in the Authorization header. The dashboard and signed-in API reference can also use your account's access token.

Get your first API key

  1. Sign in to the dashboard and select the Project your integration will use.
  2. Open Settings > API Keys and create a key with a description that identifies its use, such as Production backend.
  3. Copy the key's token and store it securely on your backend.

Select a Project before creating the key to restrict it to that Project. Creating a key requires key-management permissions. If you cannot create one, ask an administrator for access or a key for your integration.

Keep API keys out of browser code

Do not include a Reecall API key in browser bundles, browser requests, or public repositories. Make Reecall API requests from your backend. For browser calls, pass only the returned LiveKit connection credentials to the client.

Authenticate a request

Use the token value, not the key record's id:

Code
GET /data_next/ai/STS/ Authorization: Bearer {your-api-key}

The response is an array of available STS models. This request also checks that your key can authenticate without creating or changing resources.

Paths in this article include /data_next and are relative to your deployment host. The Data API server URL in the API reference already includes this prefix, so do not append it twice. All IDs and tokens in the examples are placeholders.

Key scopes

ScopeprojectId on the keyAccess
ProjectA Project IDResources within that Project, plus shared catalogs such as AI models
OrganizationnullResources across Projects in the Organization, plus organization-level management endpoints

Use a project-scoped key for an integration that only needs one Project. Use an organization-scoped key for provisioning or managing several Projects in the same Organization. Project-scoped keys cannot manage Projects or API keys.

Creating project resources

For resources such as Assistants, Channels, and Hooks:

  • A project-scoped key supplies projectId automatically.
  • With an organization-scoped key, include the destination projectId in the creation payload.

The key supplies organizationId in either case. Shared catalogs and resources that support Organization scope have different requirements; consult the endpoint's schema.

See Organizations & Projects to choose project boundaries and retrieve a Project ID.

Create additional keys through the API

Use an existing organization-scoped API key for key-management requests. Your first key comes from the dashboard; creating another key through the API already requires authentication.

To create a project-scoped key, supply its projectId:

Code
POST /data_next/core/apiKeys/ Authorization: Bearer {your-org-scoped-key} Content-Type: application/json { "comment": "Production backend", "projectId": "{your-project-id}" }
JSONCode
{ "id": "{your-api-key-id}", "comment": "Production backend", "token": "{your-generated-api-key}", "projectId": "{your-project-id}", "organizationId": "{your-organization-id}" }

Use token for authentication and id for key-management operations. To create an organization-scoped key, omit projectId from the creation payload. Its returned projectId is null.

Store the token securely. Authorized key-management requests can retrieve it later, and the dashboard lets you reveal or copy an existing key.

List and revoke keys

These requests require an organization-scoped key:

Code
GET /data_next/core/apiKeys/ Authorization: Bearer {your-org-scoped-key}
Code
DELETE /data_next/core/apiKeys/{your-api-key-id} Authorization: Bearer {your-org-scoped-key}

Deleting a key prevents subsequent Reecall API requests using that token. To replace a key, create its replacement, update your backend, verify a request with the new token, then revoke the old key. Revoke an exposed key as soon as possible.

Troubleshoot access errors

Missing or invalid credentials can return 403 with code UNAUTHORIZED. For example:

JSONCode
{ "message": "Insufficient permissions.", "code": "UNAUTHORIZED", "status": 403, "context": { "required": "AUTHENTICATED", "current": "EVERYONE" } }
SymptomCheck
Missing or invalid tokenSend Authorization: Bearer followed by the token, not the key's id. Check that the key has not been revoked.
403 on a management endpointUse an organization-scoped key for Project and API key management.
Empty results or 404 for an existing resourceCheck that the key and resource belong to the same Project or Organization. Resources outside the key's scope may not be visible.

Next steps

  • Quickstart uses a project-scoped key to create your first browser conversation.
  • Organizations & Projects explains ownership and project isolation.
  • Variables covers storing credentials used by an Assistant's integrations.
Last modified on