lumen-oss · mrcjkb · Aug 13, 2026
diff --git a/docs/guides/access-tokens.md b/docs/guides/access-tokens.md
@@ -0,0 +1,75 @@
+---
+slug: /guides/access-tokens
+id: access-tokens
+title: How to configure access tokens
+sidebar_label: Access tokens
+---
+
+Lux fetches rocks, rockspecs, and git dependencies over HTTP(S).
+Access tokens authenticate you with the host, which is required for private
+repositories.
+
+Even for public repositories, configuring an access token is worthwhile:
+authenticated requests are less likely to be rate limited.
+
+## Configure tokens
+
+You can configure access tokens either in the `[access_tokens]` section of your
+config file, or via the `LUX_ACCESS_TOKENS` environment variable.
+
+Open your config file with:
+
+```sh
+lx config edit
+```
+
+Then add a `[access_tokens]` section, mapping each host to its token:
+
+```toml
+[access_tokens]
+"github.com" = "ghp_1234abcd"
+"gitlab.com" = "PAT:glpat-1234abcd"
+"codeberg.org" = "cb_1234abcd"
+"git.sr.ht" = "s3cr3t"
+```
+
+:::note
+On GitHub Actions runners, Lux will automatically pick up the [`GITHUB_TOKEN`](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token)
+environment variable.
+:::
+
+## Token types
+
+Lux recognizes the following token types:
+
+| Type | Syntax | Hosts |
+|---|---|---|
+| Plain token | `<token>` | GitHub, Codeberg, and other Gitea-compatible forges, and SourceHut |
+| GitLab personal access token | `PAT:<token>` | GitLab |
+| GitLab OAuth2 token | `OAuth2:<token>` | GitLab |
+
+The type determines how the token is sent, e.g. a GitLab personal access token
+is sent in the `PRIVATE-TOKEN` header, while a plain token is sent in the
+`Authorization` header.
+
+## Environment variable
+
+As an alternative to the config file, set the `LUX_ACCESS_TOKENS` environment
+variable to a whitespace-separated list of `host=token` pairs:
+
+```sh
+export LUX_ACCESS_TOKENS="github.com=ghp_1234abcd gitlab.com=OAuth2:glpat-1234abcd"
+```
+
+## Precedence
+
+Lux resolves the token for a host in this order:
+
+1. The `LUX_ACCESS_TOKENS` environment variable.
+2. The `[access_tokens]` section of the config file.
+3. The `GITHUB_TOKEN` environment variable, for `github.com` only.
+
+## Git dependencies
+
+The same tokens are used for git-over-HTTPS authentication when fetching
+[git dependencies](/reference/lux-toml#git-dependencies).
diff --git a/docs/guides/index.md b/docs/guides/index.md
@@ -18,6 +18,9 @@ Want to get better at using Lux? Look no further than this set of guides.
 - [How to use Lux with a rockspec file](/guides/rockspec)
 - [How to declare a workspace with multiple projects](/guides/multi-project-workspaces)
 
+## Configuration
+- [How to configure access tokens](/guides/access-tokens)
+
 ## Code Hygiene
 - [How to test a Lua project](/guides/testing)
 - [How to format and lint a Lua project](/guides/formatting-linting)

diff --git a/docs/reference/environment-variables.md b/docs/reference/environment-variables.md
@@ -15,3 +15,15 @@ Secret key for generating TOTP codes for two-factor authentication.
 
 Lux reads this variable to automatically generate 2FA codes during `lx upload`, eliminating the need for the `--tfa-code` flag.
 Obtain the secret from the [2FA settings](https://luarocks.org/settings/two-factor-auth) page on LuaRocks.
+
+## `LUX_ACCESS_TOKENS`
+
+Access tokens for fetching from private repositories, as a whitespace-separated
+list of `host=token` pairs.
+
+```sh
+export LUX_ACCESS_TOKENS="github.com=ghp_1234abcd gitlab.com=OAuth2:glpat-1234abcd"
+```
+
+See [How to configure access tokens](/guides/access-tokens) for supported token
+types and hosts.
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -11,5 +11,5 @@ sidebar_position: 3
 Detailed reference documentation for Lux configuration and tooling.
 
 - [lux.toml reference](/reference/lux-toml). All fields, build backends, and test specifications.
-- [Environment variables reference](/reference/environment-variables). `LUX_API_KEY` and `LUAROCKS_2FA_SECRET`.
+- [Environment variables reference](/reference/environment-variables). `LUX_API_KEY`, `LUAROCKS_2FA_SECRET`, and `LUX_ACCESS_TOKENS`.
 - [CLI reference](/reference/cli). All `lx` subcommands and global options, auto-generated from the man page.
diff --git a/docs/tutorial/04-adding-dependencies.md b/docs/tutorial/04-adding-dependencies.md
@@ -25,6 +25,11 @@ Added argparse 0.7.1
 This may take a while depending on your internet connection!
 :::
 
+:::tip
+To avoid hitting rate limits on hosts
+like GitHub, see [How to configure access tokens](/guides/access-tokens).
+:::
+
 ## Testing Our Changes
 
 To check whether `argparse` is loaded, we can enter a Lua REPL and play around