Overview

Authentication is how TIE verifies who is making a request. Every call to TIE — whether it comes from a user's browser, a mobile app, or a backend service — must include a credential that proves the caller's identity.

TIE supports two authentication methods. User tokens let real people sign in through email/password or OAuth providers (Google, Apple). Service accounts let backend services call TIE directly using a shared secret, without going through the user sign-in flow. Both methods result in a Bearer token passed in the Authorization header.

Which method you choose depends on who is calling and whether the request needs a user's context (memory, persona, conversation history). This page helps you pick the right one.

What are you trying to do?

I want to...	Method	Guide
Let users sign in from my web or mobile app	User tokens	User tokens
Call TIE from my backend service on behalf of a user (e.g. WhatsApp webhook, cron job)	Service account + X-On-Behalf-Of	Service accounts
Call TIE from my backend for a one-shot task (e.g. title generation, summarization)	Service account (stateless)	Service accounts
Verify a TIE token in my own backend	Token verification	Verifying tokens

Choose the right authentication method

flowchart TD
    Start["Who is making the request?"]
    Start -->|"A real user<br/>(browser or mobile)"| UserToken["Use <b>user tokens</b><br/>User signs in via email/password or OAuth"]
    Start -->|"A backend service"| ServiceQ["Does it need a specific user's<br/>memory and persona?"]
    ServiceQ -->|Yes| ServiceUser["Use <b>service account + user</b><br/>Pass AUTH_SECRET + X-On-Behalf-Of"]
    ServiceQ -->|No| ServiceOnly["Use <b>service account</b> (stateless)<br/>Pass AUTH_SECRET only"]

    UserToken --> UserLink["<a href='/authentication/user-tokens/'>User tokens guide →</a>"]
    ServiceUser --> ServiceLink["<a href='/authentication/service-accounts/#service-acting-as-a-user'>Service + user guide →</a>"]
    ServiceOnly --> StatelessLink["<a href='/authentication/service-accounts/#service-only-stateless'>Stateless guide →</a>"]

    style Start fill:#fff7ed,stroke:#F68220,color:#181818
    style UserToken fill:#f0f9ff,stroke:#3b82f6,color:#181818
    style ServiceQ fill:#fff7ed,stroke:#F68220,color:#181818
    style ServiceUser fill:#f0f9ff,stroke:#3b82f6,color:#181818
    style ServiceOnly fill:#f0f9ff,stroke:#3b82f6,color:#181818
    style UserLink fill:#ffffff,stroke:#d1d5db,color:#181818
    style ServiceLink fill:#ffffff,stroke:#d1d5db,color:#181818
    style StatelessLink fill:#ffffff,stroke:#d1d5db,color:#181818

Authentication methods

Method	Authorization header	Features	Use case
User tokens	Bearer <JWT from TIE Auth>	Memory, persona, threads, profile	Browser and mobile apps where a user signs in
Service + user	Bearer <AUTH_SECRET> + X-On-Behalf-Of	Memory, persona, threads (same as user token)	Backend acting on behalf of a specific user
Service only	Bearer <AUTH_SECRET>	Threads only — no memory, no persona	Stateless backend tasks with no user context

Key concepts

• Bearer token — A string passed in the Authorization: Bearer <token> header. For user tokens, this is a JWT signed by Firebase. For service accounts, this is the AUTH_SECRET value.
• User UUID — TIE's canonical user identifier (user.id). Deterministic — the same Firebase user always produces the same UUID across all services. Backend services pass this in X-On-Behalf-Of to act on behalf of a user.
• AUTH_SECRET — A shared secret issued by the TIE team for backend service authentication. Never expose it to browsers or mobile clients.

What other pages assume

All other docs pages assume you already have a Bearer token. When you see Authorization: Bearer $TOKEN in an example, it means either a user JWT or AUTH_SECRET depending on your integration type. Refer back to this page if you need to know how to get one.