1# 1Password service account on a remote server
2
3Use a 1Password service account when the T3 Code server runs on a machine you are not sitting at, such as a
4headless host, a VM, or a [background service](./background-service.md) you reach through
5[remote access](./remote-access.md).
6
7Signing in to 1Password through its desktop app asks for approval on the server's machine. A remote user
8never sees that prompt, so the secret cannot be read. A service account signs in with a token instead, so
9nothing needs approving.
10
11For the basics, see [Secrets](./secrets.md). To use a self-hosted Connect server instead, see
12[1Password Connect](./secrets-1password-connect.md).
13
14## Set it up
15
16In 1Password, open Developer, then Service Accounts, and create one.
17Give it read access to only the vaults T3 Code needs. Access is fixed when the account is created, and a
18 service account cannot reach Personal, Private, or Employee vaults.
19Copy the token. It is shown once.
20Install the [1Password CLI](https://developer.1password.com/docs/cli/get-started/) (`op`) on the machine
21 that runs the T3 Code server.
22Put `OP_SERVICE_ACCOUNT_TOKEN` in the server's environment. For a background service, add it to
23 `service.env` and restart the service. See
24 [Configure the service environment](./background-service.md#configure-the-service-environment).
25In **Settings → Secrets**, select **Add provider**. The account is required, but `op` ignores it while
26 the token is set, so enter any sign-in address such as `my.1password.com`.
27
28Then use references as usual, for example `op://Automation/provider-token/credential`.
29
30## Check that it works
31
32On the server's machine, set `OP_SERVICE_ACCOUNT_TOKEN` in your shell to the same token the server uses,
33then read a secret with a clean environment so only the token can sign in:
34
36env -i PATH="$PATH" HOME="$(mktemp -d)" OP_SERVICE_ACCOUNT_TOKEN="$OP_SERVICE_ACCOUNT_TOKEN" \
37 op read --no-newline "op://Automation/provider-token/credential" >/dev/null && echo "Secret read"
39
40If it prints `Secret read`, the token can read the secret. This checks your shell, not the server's own
41environment. To confirm the server can read it, use the reference in a setting and then use the feature
42that needs it. If the server cannot read the secret, that feature shows an error naming the secret provider.
43
44## Things to know
45
46Agents run with the server's environment, so an agent can use the token to read anything the service
47 account can. Give it only vaults whose items you would let an agent read.
48A name in a reference can contain letters, digits, spaces, `.`, `_`, and `-`. An item titled
49 `Service Token: CI` cannot be written as a reference, so use its item ID instead, for example
50 `op://Automation/<item-id>/credential`.
51T3 Code waits up to 45 seconds for 1Password. After that the secret counts as unreadable and the feature
52 that needs it shows an error naming the secret provider.
53Do not set `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` in the same environment.