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

# Built-in variables

> Read values the host passes in, such as the caller's token, without declaring them.

A **built-in variable** is a value the host running your script passes in. You read it like any variable, but you don't declare it. Which built-ins exist depends on the host. A [Stellarium](https://docs.stellarium.sh/concepts/built-in-variables) node, for example, passes the caller's run token as `jwt`.

```kotlin theme={null}
request WhoAmI {
    return jwt.sub // a field of the built-in jwt object
}
```

## Built-ins are read-only

A built-in can't be reassigned, and unlike a [`const`](https://docs.requestscript.org/language/variables#const) its contents can't be changed either:

```kotlin theme={null}
request ReadOnly {
    jwt = null          // Error: Cannot assign to 'jwt' because it is a const
    jwt.sub = "other"   // Error: Cannot set property 'sub' because the object is read-only
}
```

This holds at every depth, for objects and lists inside the built-in too. A variable you assign a built-in to refers to the same read-only value. To work with a field, copy it into a variable of its own:

```kotlin theme={null}
request CopyField {
    var label = jwt.sub
    label = label + " (via script)" // OK: label is an ordinary var
    return label
}
```

## Built-in names are reserved

You can't declare a variable with a built-in's name, in any scope:

```kotlin theme={null}
request Reserved {
    var jwt = 1 // Error: 'jwt' is a built-in variable and cannot be redeclared
}
```

A [contract](https://docs.requestscript.org/contracts/overview.md) can't have a parameter with a built-in's name either. That is a parameter error.

A built-in can be `null`. For example, a host may pass `jwt` as `null` when the caller didn't use a token. Its name is still reserved:

```kotlin theme={null}
request Caller {
    if (jwt == null) {
        return "anonymous"
    }
    return jwt.sub
}
```

## Types

Built-ins are converted the same way as resource results: whole numbers become `int32` or `int64`, other numbers `decimal`, and objects and lists are converted field by field. See [Types](https://docs.requestscript.org/language/types.md).

## Passing built-ins from a host

Hosts pass built-ins with the `builtins` option of `interpret` or `interpretParsed` (requestscript 1.3.0 and later):

```ts theme={null}
import { interpret } from "requestscript";

const result = await interpret(source, {
  builtins: { jwt: { sub: "cli_123", org: "org_456" } },
});
```

Each name must be an identifier, and not a keyword. The interpreter copies the values, so a script never changes the host's objects.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.