> ## Documentation Index > Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt > Use this file to discover all available pages before exploring further. # cockroach auth-session To create and manage web sessions and authentication tokens to the HTTP interface from the command line, use the `cockroach auth-session` [command](/docs/stable/cockroach-commands.md) with the appropriate subcommands and flags. ## Subcommands | Subcommand | Usage | | - | - | | `login` | Authenticate a user against a running cluster's HTTP interface, generating an HTTP authentication token (a "cookie") which can also be used by non-interactive HTTP-based database management tools. Must be used with a valid, existing user. May be used to generate a cookie for the `root` user. | | `logout` | Revokes all previously-issued HTTP authentication tokens for the given user. | | `list` | List all authenticated sessions to the HTTP interface, including currently active and recently expired sessions. | ## Synopsis Log in to the HTTP interface, generating an HTTP authentication token for a given user: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach auth-session login {username} [flags] ``` Log out from the HTTP interface, revoking all active HTTP authentication tokens for a given user: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach auth-session logout {username} [flags] ``` List all authenticated sessions to the HTTP interface, including currently active and recently expired sessions: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach auth-session list [flags] ``` View help: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach auth-session --help ``` ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach auth-session {subcommand} --help ``` ## Flags All three `auth-session` subcommands accept the standard [SQL command-line flags](/docs/stable/cockroach-start.md#flags). In addition, the `auth-session login` subcommand supports the following flags. | Flag | Description | | - | - | | `--expire-after` | Duration of the newly-created HTTP authentication token, after which the token expires. Specify the duration in numeric values suffixed by one or more of `h`, `m`, and `s` to indicate hour, minute, and second duration. See the [example](#log-in-to-the-http-interface-with-a-custom-expiry). **Default:** `1h0m0s` (1 hour) | | `--only-cookie` | Limits output to only the newly-created HTTP authentication token (the "cookie") in the response, appropriate for output to other commands. See the [example](#log-in-to-the-http-interface-with-limited-command-output). | ## Response The `cockroach auth-session` subcommands return the following fields. ### `auth-session login` | Field | Description | | - | - | | `username` | The username of the user authenticated. | | `session ID` | The session ID to the HTTP interface previously established for that user. | | `authentication cookie` | The cookie that may be used from the command line, or from other tools, to authenticate access to the HTTP interface for that user. | ### `auth-session logout` | Field | Description | | - | - | | `username` | The username of the user whose session was revoked. | | `session ID` | The session ID to the HTTP interface previously established for that user. | | `revoked` | The date and time of revocation for that user's authenticated session. | ### `auth-session list` | Field | Description | | - | - | | `username` | The username of the user authenticated. | | `session ID` | The session ID to the HTTP interface established for that user. | | `created` | The date and time a session was created. | | `expired` | The date and time a session expired. | | `revoked` | The date and time of revocation for that user's authenticated session. If the session is still active, this will appear as `NULL`. | | `last used` | The date and time of the last access to the HTTP interface using this session token. | ## Required roles To run any of the `auth-session` subcommands, you must be a member of the [`admin` role](/docs/stable/security-reference/authorization#admin-role). The user being authenticated via `login` or `logout` does not require any special roles. ## Considerations * The `login` subcommand allows users with the [`admin` role](/docs/stable/security-reference/authorization#admin-role) to create HTTP authentication tokens with an arbitrary duration. If operational policy requires stricter control of authentication sessions, you can: * Monitor the `system.web_sessions` table for all current and recent HTTP sessions. If you monitor this table regularly, consider adjusting the `server.log_gc.period` and `server.log_gc.max_deletions_per_cycle` [cluster settings](/docs/stable/cluster-settings.md) to fine tune garbage collection for this table. * Revoke HTTP authentication tokens as needed with the `logout` subcommand. See the [example](#terminate-all-active-sessions-for-a-user). * Set the `--expire-after` flag with a shorter duration. See the [example](#log-in-to-the-http-interface-with-a-custom-expiry). * The `logout` subcommand logs out all sessions for the given user; you cannot target individual sessions for logout. If more granular control of sessions is desired, consider setting the `--expire-after` flag with a shorter duration. See the [example](#log-in-to-the-http-interface-with-a-custom-expiry). ## Examples ### Log in to the HTTP interface Log in to the HTTP interface, by generating a new HTTP authentication token for the `web_user` user: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach auth-session login web_user ``` ``` username | session ID | authentication cookie -----------+--------------------+--------------------------------------------------------------------- web_user | 784445853689282561 | session=CIGAtrWQq7rxChIQTXxYNNQxAYjyLAjHWxgUMQ==; Path=/; HttpOnly; Secure (1 row) ``` ### Log in to the HTTP interface with a custom expiry Log in to the HTTP interface, by generating a new HTTP authentication token for the `web_user` user and specifying a token expiry of 4 hours and 30 minutes: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach auth-session login web_user --expire-after=4h30m ``` ``` username | session ID | authentication cookie -----------+--------------------+--------------------------------------------------------------------- web_user | 784445853689282561 | session=CIGAtrWQq7rxChIQTXxYNNQxAYjyLAjHWxgUMQ==; Path=/; HttpOnly; Secure (1 row) ``` ### Log in to the HTTP interface with limited command output Log in to the HTTP interface, by generating a new HTTP authentication token for the `web_user` user, limiting command output to only the generated cookie: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach auth-session login web_user --only-cookie ``` ``` session=CIGA6t2q0LrxChIQV8QCF3vuYSasR7h4LPSfmg==; Path=/; HttpOnly; Secure ``` This is useful if you intend to use the cookie with other command line tools. For example, you might output the generated cookie to a local file, and then pass that file to `curl` using its `--cookie` flag: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach auth-session login web_user --certs-dir=certs --only-cookie > $HOME/.cockroachdb_api_key $ curl --cookie $HOME/.cockroachdb_api_key https://localhost:8080/_status/logfiles/local ``` Of course you can also provide the cookie directly: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} curl --cookie 'session=CIGA8I7/irvxChIQDtZQsMtn3AqpgDko6bldSw==; Path=/; HttpOnly; Secure' https://localhost:8080/_status/logfiles/local ``` ### Terminate all active sessions for a user Terminate all active sessions for the `web_user` user: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach auth-session logout web_user ``` ``` username | session ID | revoked -----------+--------------------+----------------------------- web_user | 784445853689282561 | 2022-08-02 18:24:50.819614 web_user | 784447132063662081 | 2022-08-02 18:24:50.819614 web_user | 784449147579924481 | 2022-08-02 18:47:20.105254 web_user | 784449219848241153 | 2022-08-02 18:47:20.105254 (4 rows) ``` Note that the output may include recently revoked sessions for this user as well. ### List all sessions List all authenticated sessions to the HTTP interface, including currently active and recently expired sessions: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach auth-session list ``` ``` username | session ID | created | expires | revoked | last used -----------+--------------------+----------------------------+----------------------------+----------------------------+----------------------------- root | 784428093743988737 | 2022-08-02 16:47:36.342338 | 2022-08-02 17:47:36.341997 | NULL | 2022-08-02 16:47:36.342338 root | 784428586862215169 | 2022-08-02 16:50:06.830294 | 2022-08-02 17:50:06.829974 | NULL | 2022-08-02 16:50:06.830294 web_user | 784447132063662081 | 2022-08-02 18:24:26.37664 | 2022-08-02 19:24:26.376299 | 2022-08-02 18:24:50.819614 | 2022-08-02 18:24:26.37664 web_user | 784449147579924481 | 2022-08-02 18:34:41.463345 | 2022-08-02 19:34:41.463006 | 2022-08-02 18:47:20.105254 | 2022-08-02 18:34:41.463345 ``` A value of `NULL` in the `revoked` column indicates that the session is still active. ## See also * [`cockroach` Commands Overview](/docs/stable/cockroach-commands) * [DB Console Overview](/docs/stable/ui-overview.md)