# Auth


Log in and out. [Conventions](/cli/reference#conventions) apply, except for
output: `auth login` and `auth logout` print only commentary on stderr, and
`auth status` prints the same plain text on stdout with `--json` or `--quiet`.
Giving both is still rejected, as on every command.

## Login

Mint an API token from console credentials and store it for later commands.
See [Create API Token](/api/v2/authentication#post-apiv2authapitoken).

The token is an API token, the same kind minted on the My Account > API Tokens
page, and it is listed there. It is valid for one year and counts toward the
account's cap of 10 active API tokens. Revoking it on that page, or changing
the account password, ends it sooner: a password change revokes every API
token on the account.

| Flag | Input |
| --- | --- |
| `--email` | account email, prompted for on a terminal and required to mint when stdin is not a terminal |
| `--password` | account password, prompted for on a terminal and read from stdin when stdin is not a terminal |

```bash
intuizi auth login
```

`--password` puts the password in shell history, so prefer the prompt.

`--base-url` picks the console. Login saves it beside the token, so later
commands use it without the flag, and `https://console.intuizi.com` applies
when none is stored. A stored token is only ever sent to the console that
minted it.

Logging in again keeps a working token already stored for the same console
rather than minting another. That holds when `--email` is left out or names
the account the token was minted for, ignoring case, and stderr names that
account. An `--email` for another account mints a token for that account and
replaces the stored one. So does a stored token that has expired or been
revoked. A different `--base-url` mints a token for that console and makes it
the one in use. In the OS credential store, the previous console's token stays
stored under that console: a plain `auth logout` does not remove it,
`auth status` does not show it, and logging back in to that console mints
another token rather than reusing it. Run
`intuizi auth logout --base-url <previous console>` to remove it. A replaced
token that still works stays valid on the console until it expires or is
revoked. To get a fresh token for the same account, run `intuizi auth logout`
first.

A token stored by v0.1.3 or earlier has no account recorded with it. A bare
`auth login` keeps it, and the first `auth login --email` mints a new one that
records the account. Such a token also stays in the config file after the
upgrade, and `auth status` reports it there. The next `auth login` that keeps
or replaces it moves the token to the OS credential store when there is one.

### Token storage

The token goes to the OS credential store when there is one: the macOS
Keychain, Windows Credential Manager, or the Linux secret service. Where there
is none, as in most containers, CI runners, and SSH sessions, it goes to the
config file instead, written owner-only. Set `INTUIZI_NO_KEYRING=1` to keep it
in the config file anyway. Any non-empty value switches the store off, except
one that reads as false: `0` and `false` leave it on, as leaving it unset does.
Set it before `auth login` and keep it set. While it is set, a token
already in the credential store is not read, so commands report that you are
not logged in, and `auth login` mints a new token, which counts toward the
account's 10.

The config file holds the base URL, the expiry, and the account email either
way. It is `~/.config/intuizi/config.json`, or
`$XDG_CONFIG_HOME/intuizi/config.json` when that is set, and
`%AppData%\intuizi\config.json` on Windows. Outside Windows, a config file with
permissions looser than `0600` is refused until it is `chmod 600` again.

When the credential store does not answer within two seconds, a command that
needs the token held there fails. So do `auth login`, before it mints
anything, and `auth logout`, whatever the config file holds. Unlock it and try
again. Setting `INTUIZI_NO_KEYRING=1` also gets past it: `auth logout` then
clears a token held in the config file, but a token held in the store is not
read or removed, so the next `auth login` mints a new one. That logout still
clears the account and expiry recorded for the store's token, and says there
was no stored token to remove. Once the store answers again with the variable
unset, commands use that token again, and `auth status` reports its account as
`unknown` with no expiry. Run a plain `auth logout` then to remove it. A login
that mints while the store is not answering, such as the first login on a
machine, saves the new token to the config file instead.

### Scripts and CI

Where stdin is not a terminal, the password is read from it and `--email` is
required to mint a token:

```bash
echo "$PASSWORD" | intuizi auth login --email you@example.com
```

That suits a machine that keeps its CLI config between runs: the next login
there reuses the stored token. A machine that starts with no stored token,
such as a fresh container or CI runner, mints another year-long token on every
run. The CLI never revokes them, so they fill the cap of 10 until minting
fails, on My Account > API Tokens as well. For CI, mint one token on the
My Account > API Tokens page and pass it in the `INTUIZI_API_TOKEN`
environment variable instead of running `auth login`. A password change
revokes that token too, so CI needs a new one after it:

```bash
INTUIZI_API_TOKEN=<token> intuizi audiences list
```

When `INTUIZI_API_TOKEN` is set, every command uses it in place of the stored
token. `auth status` reports it as the token in use, `auth login` warns that it
takes precedence over the stored token, and `auth logout` leaves it in place,
so commands stay authenticated until it is unset.

## Status

Reports the console, where the token in use comes from, and the account it
belongs to. For a stored token, it also reports when the token expires. Calls
no endpoint unless `--verify` is given.

| Flag | Input |
| --- | --- |
| `--verify` | make one request to check that the API still accepts the token |

```bash
intuizi auth status
```

```
Base URL: https://console.intuizi.com
Token:    present (from /home/you/.config/intuizi/config.json)
Account:  you@example.com
Expires:  2027-09-26 (in 364 days)
```

`Token:` reads `present (in the OS credential store)` when the store holds the
token, and `present (from INTUIZI_API_TOKEN)` when the variable is set.
`Account:` reads `unknown` for a token from `INTUIZI_API_TOKEN`, whose account
is not known locally, for a token stored before accounts were recorded, and
for a store-held token whose account a logout with `INTUIZI_NO_KEYRING` set
cleared (see [Token storage](/cli/reference/auth#token-storage)).
`--verify` adds `Verified: the API accepted this token`, or exits `1`. Stderr
says `token rejected` when the API refuses the token (a `401`), and
`could not verify the token` on any other failure, such as an API that could
not be reached, a server error, or a `429` that outlasted the retries. It
checks the token, not the account.

With no token, `auth status` prints `Token:    none` and exits `1`. With a
`--base-url` other than the console the stored token belongs to, it prints
`Token:    none for this console`, sends nothing even with `--verify`, and
exits `1`. A token that expires within 30 days, or has expired, adds a warning
on stderr.

## Logout

Forgets the stored token, its expiry, and its account for the console in use.
`--base-url` names another, such as a console you logged in to before
switching. It calls no endpoint, so the token itself stays valid until it
expires, is revoked on the My Account > API Tokens page, or the account
password changes. When the credential store does not answer, logout fails and
removes nothing. See [Token storage](/cli/reference/auth#token-storage).

{{< cards >}}
  {{< card link="/developers/cli/reference/" title="Command Reference" subtitle="Every command, its flags, and the endpoint behind each one that calls the API." >}}
  {{< card link="/developers/cli/reference/audiences/" title="Audiences" subtitle="Build audiences and Lookalike Models." >}}
{{< /cards >}}