# Receptionistic API Authentication | Workspace Sessions

> Understand Receptionistic session-cookie authentication, private workspace access, API errors, and the current limits for agent integrations.

Source: https://receptionistic.com/docs/auth

Developer resources

[Setup guide](https://receptionistic.com/docs)[API reference](https://receptionistic.com/docs/api)[Authentication](https://receptionistic.com/docs/auth)[OpenAPI schema](https://receptionistic.com/openapi.json)[Agent instructions](https://receptionistic.com/agent-instructions.md)[LLM discovery file](https://receptionistic.com/llms.txt)

[Receptionistic](https://receptionistic.com/)[Docs](https://receptionistic.com/docs)Authentication

## Receptionistic API authentication.

Workspace reads use the existing Receptionistic sign-in session. Understand the access boundary before connecting an agent to business knowledge, contacts, calendars, or conversation history.

### Sign in through the workspace

Receptionistic is in private testing, and portal access is limited to the owner. A human signs in through [the Receptionistic workspace](https://receptionistic.com/app) using an available sign-in method. The public `GET /api/auth/options` endpoint reports which sign-in methods and registration options are enabled. The presence of API documentation does not enable registration or authorize another account.

The [workspace read API](https://receptionistic.com/docs/api) does not offer API keys, bearer tokens, or OAuth authorization for third-party service integrations. A Google sign-in option, when enabled, is a human sign-in method, not an OAuth API grant for an agent. A separate service integration must be agreed and implemented before a runtime can assume unattended access.

### Let the transport handle the session

A successful sign-in sets the `reception_session` cookie. It is `HttpOnly`, uses `SameSite=Lax`, has path `/`, and is `Secure` in production. The session expires seven days after it is issued. Sign-out invalidates the session; an expired or invalidated session must be replaced through human sign-in.

Same-origin browser requests can use the browser’s existing cookie handling. The cookie is not readable by page JavaScript. Do not extract cookies, copy them into source code, ask a model to supply them, or include them in tool arguments. Any agent tool must run through a trusted transport already authorized to use the relevant workspace session.

The [OpenAPI document](https://receptionistic.com/openapi.json) expresses this HTTP cookie requirement. Its security declaration describes the existing session mechanism; it does not create a separate developer credential.

### Separate public checks from private reads

`GET /api/health` and `GET /api/auth/options` are public. Knowledge, contacts, appointments, availability, and call history require the session cookie. The server derives the workspace from the signed-in user, so an agent does not supply a workspace or business ID to these operations.

Use the [agent instructions](https://receptionistic.com/agent-instructions.md) to select a suitable read operation. The published schema covers reads only. Reading availability does not confirm an appointment, reading a conversation does not place a call, and access to data does not authorize sharing it elsewhere.

### Recover from an access failure

HTTP 401 with `{"error":"Please log in to continue."}` means that no valid session was found. Stop protected requests and ask the human to sign in through the workspace. Do not retry credentials or attempt another authentication mechanism.

HTTP 403 with a private-testing access message means that the account is not allowed. This is an access decision, not a temporary sign-in error. The server clears disallowed sessions. Access changes require the product owner; the [contact page](https://receptionistic.com/contact) is available for enquiries.

HTTP 404 from a single-call read means that no matching call is available in this workspace. Use an ID returned by `listCalls` and respect that boundary. Keep credentials out of logs, keep private responses out of shared caches, and pass only the task-relevant data to a model.