Credential store plugin for HTTPie, attaches auth to ongoing request.
[!NOTE]
The plugin was renamed from
httpie-credential-store
tohttpie-auth-store
primarily due to backward incompatible changes and because the new name better reflects its nature.
HTTPie Auth Store is an HTTPie authentication plugin that automatically selects the appropriate authentication type and payload from a file containing authentication bindings, then uses them for the current request. No more memorizing or searching for tokens, usernames, or passwords — simply add them to the authentication store, and the plugin handles the rest. This plugin also supports various secret storage options, such as system keychains and password managers (see supported Secret providers).
Eager to get started? Just start with installing!
httpie cli plugins install httpie-auth-store
or via pip
in the same python environment where HTTPie is installed:
python3 -m pip install httpie-auth-store
[!IMPORTANT]
Do not forget to pass
-A store
or--auth-type store
to HTTPie in order to activate the plugin.
Once installed, the plugin looks for auth_store.json
located in the HTTPie
configuration directory. On macOS and Linux, it tries the following locations:
$HTTPIE_CONFIG_DIR/auth_store.json
, $HOME/.httpie/auth_store.json
and
$XDG_CONFIG_HOME/httpie/auth_store.json
; on Windows —
%HTTPIE_CONFIG_DIR%\auth_store.json
and %APPDATA%\httpie\auth_store.json
[!NOTE]
The authentication store can be automatically created with few examples on first plugin activation, e.g.
http -A store https://pie.dev/bearer
.
The authentication store is a JSON file that contains two sections: bindings
and secrets
:
{
"bindings": [
{
"auth_type": "bearer",
"auth": "$GITHUB_TOKEN",
"resources": ["https://api.github.com/"]
},
{
"id": "bots",
"auth_type": "bearer",
"auth": "ZWFzdGVyIGVnZwo",
"resources": ["https://api.github.com/"]
},
],
"secrets": {
"GITHUB_TOKEN": {
"provider": "system",
"service": "github.com",
"username": "ikalnytskyi"
}
}
}
Each binding is a JSON object that contains the following keys:
id
(str, optional) is an authentication binding ID that can be used to
overcome ambiguity when two or more bindings are matched.
auth_type
(str, required) is an authentication type supported by HTTPie,
either natively or via third-party plugins. See Authentication types for
details.
auth
(str, optional) is an authentication payload for the given
authentication type. Required for certain authentication types, optional for
others. Tokens started with $
are replaced with secrets referred by those
tokens. The $
sign must be escaped ($$
) to remain untouched.
resources
(List[str], required) is an array of URLs to activate this
binding for. Must contain both scheme and hostname.
Each secret is a KV-pair, where key is a secret name, and value is either a
secret itself or a JSON object that specified how a secret must be retrieved
from secure storage. The JSON object must contain the provider
key. Presence
of other keys are provider dependent (see Secret providers section below).
Once the authenticate store is set up, just pass -A store
to HTTPie to
activate the plugin and perform some magic for you.
http -A store https://api.github.com
If there are two or more authentication bingind in the store that match the
same resource, you can select appropriate binding by providing a binding ID by
passing -a
or --auth
to HTTPie. This might come handy when you have
multiple accounts on the same web resource.
http -A store -a bots https://api.github.com
HTTPie Auth Store supports both built-in and third-party HTTPie authentication types as well as provides few authentication types on its own.
[!TIP]
It's advised to store your secrets in password managers instead of storing them directly in the authentication store file.
The 'Basic' HTTP authentication type as defined in RFC 7617. Transmits credentials as username/password pairs, encoded using Base64.
{
"auth_type": "basic",
"auth": "ihor:p@ss"
}
where
auth
is a :
-delimited username/password pairThe 'Digest' HTTP authentication type as defined in RFC 2617. It applies a hash function to the username and password before sending them over the network.
{
"auth_type": "digest",
"auth": "ihor:p@ss"
}
where
auth
is a :
-delimited username/password pairThe 'Bearer' HTTP authentication type transmits token in the Authorization
HTTP header.
{
"auth_type": "bearer",
"auth": "t0ken"
}
where
auth
is a bearer token to authenticate withThe 'Header' authentication type is not exactly an authentication scheme. It's rather a way to set a free-formed HTTP header that may or may not contain any secret material.
{
"auth_type": "header",
"auth": "X-Secret:s3cret"
}
where
auth
is a :
-delimited HTTP header name/value pairThe 'Header' authentication type can be used to bypass any kind of limitations
imposed by built-in or third-party authentication types. For instance, you can
pass a bearer token with non-default authentication scheme, say JWT
, without
breaking a sweat.
{
"auth_type": "header",
"auth": "Authorization:JWT t0ken"
}
The 'Composite' authentication type is a not an authentication type either.
It's a way to use multiple authentication types simultaneously. It might come
handy when in addition to basic
or bearer
authentication, you have to
supply an extra secret via custom HTTP header.
{
"auth_type": "composite",
"auth": [
{
"auth_type": "bearer",
"auth": "t0ken"
},
{
"auth_type": "header",
"auth": "X-Secret:s3cret"
}
]
}
where
auth
is a list of authentication entries, as supported by HTTPieThe 'HMAC' authentication type is not built-in and requires the httpie-hmac
plugin to be installed first. Its only purpose here is to serve as an example
of how to use a third-party authentication type in the authentication store.
{
"auth_type": "hmac",
"auth": "secret:czNjcjN0Cg=="
}
where
auth
is a HMAC specific authentication payloadThe plugin supports some secret providers that can be used to retrieve tokens, passwords and other secret materials from various secured storages.
The 'Sh' secret provider retrieves a secret from the standard output of the shell script. This is a universal approach that can be used to retrieve secrets from unsupported password managers using their command line interfaces.
{
"provider": "sh",
"script": "cat ~/path/to/secret | tr -d '\n'"
}
where
script
is a shell script to executeThe 'System' secret provider, as the name suggests, retrieves a secret from your system keychain. It may be KWallet, GNOME Keyring, macOS Keychain or even Windows Credential Locker.
{
"provider": "system",
"service": "github",
"username": "ikalnytskyi"
}
where
service
is a service to retrieve a secret fromusername
is a username to retrieve a secret fromThe 'Password Store' secret provider invokes the pass
executable on your
system, and retrieves the secret from the first line of referred record.
{
"provider": "password-store",
"name": "github.com/ikalnytskyi"
}
where
name
is a password-store entry name to retrieve a secret fromQ: How to get know what authentication is used for the given request?
A: You can run HTTPie with --offline
argument to print the request
header along with injected authentication credentials.