Actors

actor_id identifies the subject whose experience is relevant to a request. It is an attribution address, not an authentication mechanism.

All /v1/messages requests require both the project API key and a valid actor token. Request an actor token from POST /v1/actor-tokens using the project key, mind_id, and actor_id, then send the returned value in the x-mind-actor-token header. The token authorizes the backend to act for that actor in that mind; actor_id by itself does not.

This two-step flow prevents a caller from changing the actor_id in a message and impersonating another actor. Keep the project key and actor token on a trusted backend, never in a browser, mobile client, user-supplied tool input, or model output.

Derive IDs on your backend

Map your authenticated account or tenant identity to a stable, opaque value. Do not accept an actor ID directly from a browser, mobile client, user-supplied tool argument, or model output.

Good IDs are stable and non-sensitive:

customer_7f92c1

Avoid email addresses, names, access tokens, session IDs, or other personal or secret data in the identifier itself.

Your authorization layer remains responsible for deciding which caller may request or use a token for which actor.