HTTPie --session: Reuse Auth and Cookies

http --session=name stores cookies, auth, and headers so later requests to the same host reuse them.

For a smoke test that logs in and then hits protected endpoints, sessions save you from threading a token through every call. HTTPie writes the state to a JSON file keyed by host.

What it does

--session=<name> creates or reuses a named session stored under the HTTPie config directory, scoped to the request host. Cookies set by the server, plus any auth and custom headers, are saved and replayed on subsequent requests using the same session name. --session=./file.json uses an explicit path instead of a named store, and --session-read-only reuses without updating.

Common usage

# log in once, persist the cookie
http --session=ci POST example.com/login user=bot pass=secret
# reuse the session for a protected call
http --session=ci GET example.com/api/profile
# path-based session file, read-only replay
http --session-read-only=./ci.json GET example.com/api/data

Options

In CI

Named sessions are scoped per host, so a session created against one hostname will not apply to another. Use a path-based --session=./ci.json when you want the session file to live in the workspace and be cleaned up with the job, rather than in the runner's home directory.

Common errors in CI

A protected request returning 401 despite a prior login usually means the session name differs between calls, or the login and the protected call target different hosts (sessions are host-scoped). If the session file is not found, HTTPie silently starts a new empty one, so a typo in the name looks like a lost login.

Related guides