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

# SSO sign-in for ValarCode

> Engineers sign in through your identity provider instead of holding a coding key, and your directory groups decide how their requests route

Private Preview

With SSO sign-in on, engineers run `valar login` and sign in through your identity provider. Each
gets a personal sign-in on their machine that lasts a length you choose, and there is no key to hand
out. Anyone your identity provider lets into your organization can sign in. Connect your directory,
and only the people it lists can sign in, its groups decide how each person's requests route, and a
deactivation there ends their sign-in.

Coding keys keep working beside sign-ins: CI jobs, scripts, agents, and the
[automation API](https://docs.valarhq.ai/valarcode/key-automation.md) carry on as before, and anyone whose role can create
coding keys still can, unless you turn on [Block coding keys](#block-coding-keys). Inference API
keys are not affected. Usage, savings, and request history are recorded under the engineer's work
email. The [usage API](https://docs.valarhq.ai/usage-endpoints.md#valarcode-analytics) reports each engineer's sign-ins as a
row named by that email.

## Before you start

* [Single sign-on](https://docs.valarhq.ai/access/sso.md) connected: the **Single sign-on** row under
  **Settings → Sign-in & SSO** reads **Connected**.
* The `valar` CLI 1.1.20 or later on each engineer's machine. An older CLI cannot sign in: the
  browser shows **Update required**, and the engineer runs `valar upgrade`, then `valar login` again.
* To route by group, or to end a sign-in when someone is deactivated,
  [connect your directory](https://docs.valarhq.ai/access/directory.md).

## Turn it on

1. Open **Settings → Sign-in & SSO** and find **SSO sign-in for ValarCode**.
2. Choose how long a sign-in lasts: 1, 7, 14, or 28 days. The default is 28.
3. Turn the switch on.

From then on, `valar login` signs engineers in through your identity provider instead of creating a
key. Only admins can change the setting. Shortening the length also ends sign-ins older than the
new length.

## Block coding keys

With SSO sign-in on, **Block coding keys** on the same card makes sign-ins the only ValarCode
credential. Every coding key in your organization is refused with `403 sso_required` and the
message "Your organization requires SSO for ValarCode. Run `valar login` to sign in." On a machine
that still holds a key, `valar login` and `valar <tool> on` both open the browser sign-in and wait
for it instead of using the key; where no browser can open (over SSH, or a Linux session with no
display) and there is no terminal, they stop with "this machine signs in to ValarCode through your
identity provider: run `valar login` in a terminal to sign in again" and change nothing. Sign-ins
and inference API keys are not affected. The [automation API](https://docs.valarhq.ai/valarcode/key-automation.md)
credential still lists and revokes keys, but a key it creates is refused like any other while the
block is on.

A key that was answering can keep answering for up to 30 seconds after you turn the block on.
Turning SSO sign-in off also turns the block off.

## Sign in on a machine

```bash theme={"system"}
valar login
```

`valar` opens your organization's sign-in in the browser. Sign in through your identity provider;
the browser shows **Signed in as** your email, and the terminal already has the sign-in.

Where no browser can open, such as over SSH or in a container, sign in with a code:

```bash theme={"system"}
valar login --device
```

`valar` prints a URL and a code, and does this on its own when it finds no browser. Open the URL on
any device, sign in, and check that the page shows the same code as your terminal before you click
**Approve**. If the codes differ, close the page: someone else may have sent you the link. The code
works for 10 minutes.

`valar` then gives the sign-in to every tool already connected to Valar on this machine. Tools
connected through the [on-device proxy](https://docs.valarhq.ai/valarcode/proxy.md) use it at once; for the others, `valar`
offers to restart the tool or tells you what to do. To connect a tool for the first time, follow
its guide under [Set up](https://docs.valarhq.ai/valarcode/setup.md).

| Command | What it does |
| - | - |
| `valar logout` | Ends this machine's sign-in. If Valar cannot be reached, `valar` says so, and the sign-in stays active until it ends or you sign in again |
| `valar status` | Shows who is signed in, and whether the sign-in is still active |

A sign-in is a personal credential that only `valar` and your tools on that machine hold. It is
never shared, so there is nothing to hand out or rotate.

* It lasts the sign-in length from the moment you signed in. When it ends, run `valar login`; a
  command that connects or configures a tool signs you in again on its own.
* You have one sign-in at a time. Signing in again, on any machine, replaces it; the old one keeps
  working for up to 5 more minutes so running tools can finish.
* It ends early when you run `valar logout`, when an admin ends it, or when your directory
  deactivates or removes you. A request already running finishes; the next one is refused.

## Route by group or person

A signed-in person holds no key, so their routing comes from a **selection**: a group, or people
you pick by name, with routing of its own. Only admins can add, change, or delete selections.

1. Open **ValarCode → Setup**. With SSO sign-in on, the **Configuring** picker lists **Groups and
   people** first: **Everyone else**, then each selection, and then your **Keys**.
2. Click **New selection**. Pick people by name from **Any group**, or choose a **Group** and cover
   either all its members or people you pick. Name it if you like; an unnamed selection shows as its
   group and who it covers, such as "Research · All members" or "Research · 3 selected".
3. Set its routing exactly as you would a key's: Auto-routing or Manual, **Optimize for**, and each
   tool. A new selection starts on your organization's default routing, like a new key.

Without a [connected directory](https://docs.valarhq.ai/access/directory.md) there are no groups or people to pick: the
picker shows **Connect your directory** in place of **New selection**.

Which selection applies to a person:

* The selection that covers them. When several do, one that picks them by name wins over one that
  covers a whole group; otherwise the selection created first wins. **ValarCode → Users** shows
  which selection applies to each person.
* **Everyone else** routes on your organization's default, set under **Settings → ValarCode
  settings → Default routing for new keys**.
* A group selection covers the group's members as they are now. Someone who joins the group is
  covered; someone who leaves it is not, even if you picked them by name.
* Deleting a group in your identity provider deletes the selections on it. The people they covered
  move to another selection that covers them, or to the organization default.

Changes apply within about a minute, with no new sign-in: an edit to a selection or its routing, or
a change in your identity provider, such as someone joining or leaving a group. A person who has
just signed in routes on their selection from their first request.

## When someone leaves

Deactivate or remove the person in your identity provider, or unassign them from the app that
provisions your [directory](https://docs.valarhq.ai/access/directory.md). Once the change reaches Valar, usually within a
minute:

* their sign-in ends on every machine, and their next request is refused;
* `valar login` tells them your identity provider no longer lists them for ValarCode.

A suspension your provider does not send to the directory changes nothing. Removing or deactivating
someone also removes them from every selection that picked them by name; an **Any group** selection
left with no one is deleted with its routing. If they come back, pick them again.

Without a connected directory, a sign-in runs until it ends, unless an admin ends it.

## See and end sign-ins

The **SSO sign-in for ValarCode** card in **Settings → Sign-in & SSO** says how many people are
signed in and links to **API keys**, which lists them beside the keys: who, the machine, when they
signed in, when the sign-in ends, and whether it has been used lately. Filter by type
**SSO sign-ins** or search by email. **ValarCode → Users** has their usage, and so does the
[usage API](https://docs.valarhq.ai/usage-endpoints.md#valarcode-analytics).

To end a sign-in, click **End sign-in** on the row and confirm. Their requests are refused within a
minute, on every machine. They can sign in again; to keep them out, remove them in your identity
provider.

## Turn it off

Turning SSO sign-in off leaves coding keys as they are. Live sign-ins keep working until they end.
To move a machine to a coding key, run `valar login`: the browser page offers
**Create key and connect** to anyone whose role can create coding keys.


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