> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gavai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# authUser

> Read the currently signed-in end-user's profile, roles, and metadata.

export const ExpectedOutput = ({caption = "Expected output", children}) => <div className="gv-output">
    <div className="gv-output__label">
      <svg className="gv-output__icon" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
        <polyline points="15 10 20 15 15 20" />
        <path d="M4 4v7a4 4 0 0 0 4 4h12" />
      </svg>
      <span>{caption}</span>
    </div>
    <div className="gv-output__body">{children}</div>
  </div>;

export const ErrorTable = ({errors}) => <div className="gv-error-table" role="table" aria-label="Errors and fixes">
    <div className="gv-error-table__head" role="row">
      <span className="gv-error-table__col-head" role="columnheader">Error</span>
      <span className="gv-error-table__col-head" role="columnheader">Cause</span>
      <span className="gv-error-table__col-head" role="columnheader">Fix</span>
    </div>
    {errors.map((err, i) => <div className="gv-error-table__row" role="row" key={i}>
        <code className="gv-error-table__code" role="cell">{err.code}</code>
        <div className="gv-error-table__cause" role="cell">{err.cause}</div>
        <div className="gv-error-table__fix" role="cell">{err.fix}</div>
      </div>)}
  </div>;

export const Def = ({term, type, defaultValue, required, children}) => <>
    <dt className="gv-def-list__term">
      <span className="gv-def-list__name">{term}</span>
      {type && <span className="gv-def-list__type">{type}</span>}
      {required && <span className="gv-def-list__required">required</span>}
      {defaultValue !== undefined && <span className="gv-def-list__default">
          default <code>{defaultValue}</code>
        </span>}
    </dt>
    <dd className="gv-def-list__description">{children}</dd>
  </>;

export const DefList = ({children}) => <dl className="gv-def-list">{children}</dl>;

export const ArrowItem = ({children}) => <li className="gv-arrow-item">
    <span className="gv-arrow-item__arrow" aria-hidden="true">{"↳︎"}</span>
    <span className="gv-arrow-item__content">{children}</span>
  </li>;

export const ArrowList = ({children}) => <ul className="gv-arrow-list">{children}</ul>;

export const Eyebrow = ({label, tone = "default"}) => <div className={`gv-eyebrow gv-eyebrow--${tone}`}>
    <span className="gv-eyebrow__bar" aria-hidden="true" />
    <span className="gv-eyebrow__label">{label}</span>
  </div>;

<Eyebrow label="CAPABILITY" />

`authUser` returns the profile of the end-user signed in to the workspace, drawn from the workspace's per-workspace user pool managed by the end-user identity service. It takes no arguments — it reads from the active session. By the end of this page you can gate a block by role, pre-fill a form with the user's email, or pipe user context into another capability call. The user pool is auto-provisioned for every workspace; you do not configure the identity service directly.

## Invoke from a block

Most uses of `authUser` are inline references to its output fields rather than a standalone invocation. A common pattern is gating a block on a role:

```json admin-panel.json theme={null}
{
  "block": "DetailPanel",
  "props": {
    "schema_table": "admin_config",
    "visible_if": "authUser.roles contains 'admin'"
  }
}
```

Another is pre-filling a Form field with the signed-in user's email:

```json support-form.json theme={null}
{
  "block": "Form",
  "props": {
    "schema_table": "support_tickets",
    "fields": ["subject", "body"],
    "prefill": {
      "email": "authUser.email"
    },
    "on_submit": {
      "capability": "sendEmail",
      "args": {
        "template": "support-ticket",
        "to": "support@acme.com",
        "variables": {
          "user_email": "authUser.email"
        }
      }
    }
  }
}
```

The runtime resolves `authUser.*` references against the active session before dispatching the outer capability. If no user is signed in, the reference evaluates to `null` and `visible_if` blocks hide themselves.

## Inputs

`authUser` accepts no arguments. It reads entirely from the active session context.

## Outputs

The capability returns `null` when no user is signed in. When a user is signed in, the result contains:

<DefList>
  <Def term="user_id" type="string">Stable unique identifier for the user in the workspace's user pool.</Def>
  <Def term="email" type="string">The user's verified email address.</Def>
  <Def term="email_verified" type="boolean">Whether the user has confirmed their email address.</Def>
  <Def term="display_name" type="string">Optional display name, if the user has set one.</Def>
  <Def term="roles" type="string[]">Workspace-defined roles assigned to the user, e.g. `["admin", "editor"]`.</Def>
  <Def term="metadata" type="Record<string, unknown>">Optional key-value pairs attached to the user's profile by the workspace.</Def>
</DefList>

<Note>
  On public pages that can render for unauthenticated visitors, always check for `null` before accessing a field. Use a `visible_if` guard on any block whose render depends on `authUser`, or you will get a runtime error when a logged-out visitor lands on the page.
</Note>

## Provisioning

No manual setup. Every workspace has a user pool auto-provisioned on the end-user identity service. User accounts, role assignments, and metadata are managed through the workspace's authentication settings in the Builder.

## Error codes

<ErrorTable
  errors={[
{
  code: "invalid_input",
  cause: "The call envelope itself is malformed. `authUser` takes no args, so this is rare in practice.",
  fix: "Ensure the block invocation passes an empty `args` object or omits it entirely.",
},
]}
/>

Every error returns the standard envelope:

<ExpectedOutput caption="Error envelope">
  ```json error-envelope.json theme={null}
  {
    "ok": false,
    "error": {
      "code": "invalid_input",
      "message": "Invalid invocation envelope.",
      "details": {}
    }
  }
  ```
</ExpectedOutput>

## Related

<Columns cols={2}>
  <Card title="runQuery" icon="database" href="/capabilities/run-query">
    Query the workspace's Postgres database — row-level access uses `authUser`'s session.
  </Card>

  <Card title="End-user auth guide" icon="user" href="/guides/end-user-auth">
    Configure sign-in, role assignment, and per-page authentication.
  </Card>
</Columns>