HTTPie Credential Store is an HTTPie authentication plugin that looks for credentials using a given URL and attaches them to the ongoing HTTP request. That said, you don't need to memorize and/or look for tokens/username/passwords anymore. Simply add them to the credential store and everything else will be done for you by this plugin. It goes without saying that this plugin supports various secured secret storages such as system keychains or password managers (see keychain providers).
Eager to get started? Just start with installing!
$ python3 -m pip install httpie-credential-store
Note
Please, do not forget to activate the plugin by invoking http
with -A store
option.
Once installed, the plugin will look for credentials in the credential file. The credential file is stored in HTTPie configuration directory. So on Linux/macOS, it will look for ~/.httpie/credentials.json
, while on Windows - for %APPDATA%\httpie\credentials.json
. The credential file will not be created for you, you're fully responsible for creating one.
By its nature, the credentials file is a JSON array of credential records. Each credential record consists of the following properties:
url
(required) is a regular expression pattern that is used to map credential record to the ongoing HTTP request. I.e. if the regular expression matches URL of the ongoing HTTP request, credentials of matched record must be attached.auth
(required) is an authentication provider to use for a given record. The provider will be used to attach credentials to the ongoing HTTP request if the record is matched.id
(optional) is unique identifier of the credential record that can be used to solve ambiguousness between two or more matched credential records. By usingid
one may achieve support of multiple accounts for the same service.
Example:
[
{
"url": "api.github.com",
"auth": {
"provider": "token",
"token": "your-github-oauth-token",
"scheme": "token"
}
},
{
"id": "bots",
"url": "api.github.com",
"auth": {
"provider": "token",
"token": "bots-github-oauth-token",
"scheme": "token"
}
}
]
The example above assumes you store your secrets unencrypted in the credential file. Despite enforcing you to set sole access permissions for the credential file, it's not secured and, hence, not recommended. HTTPie Credential Store plugin can pull secrets and other sensitive information out from password managers or system keychains. For instance, you can pull your token from the password store by using the following credential record:
[
{
"url": "api.github.com",
"auth": {
"provider": "token",
"scheme": "token",
"token": {
"keychain": "password-store",
"name": "github.com/ikalnytskyi/token"
}
}
}
]
Once the credential store is filled, you're ready to use the plugin at your will. In order to activate the plugin, you must pass -A store
to http
executable.
$ http -A store https://api.github.com
Optionally, you can provide an ID of the credential record to use by passing -a
argument.
$ http -A store -a bots https://api.github.com
HTTPie Credential Store supports both built-in and third-party HTTPie authentication plugins as well as provides few authentication plugins on its own.
The 'Basic' HTTP authentication scheme as defined in RFC 7617. Transmits credentials as username/password pairs, encoded using Base64.
{
"provider": "basic",
"username": "ikalnytskyi",
"password": "p@ss"
}
where
username
is a username to authenticatepassword
is a password of the authenticating user
The 'Digest' HTTP authentication scheme as defined in RFC 2617. It applies a hash function to the username and password before sending them over the network.
{
"provider": "digest",
"username": "ikalnytskyi",
"password": "p@ss"
}
where
username
is a username to authenticatepassword
is a password of the authenticating user
The 'Bearer' HTTP authentication scheme transmits token in the Authorization
HTTP header.
{
"provider": "token",
"auth": "t0k3n"
}
where
auth
is a token of the authenticating user
The 'Header' HTTP authentication is not exactly an authentication scheme. It's rather a way to pass any free-formed HTTP header with secret or not.
{
"provider": "header",
"name": "X-Extra-Key",
"value": "k3y"
}
where
name
is an HTTP header name to usevalue
is an HTTP header value to pass
This is a fake authentication scheme even in terms of this plugin. It does no auth but chains and applies one or more providers simultaneously. It's something you will (likely) never use.
{
"provider": "multiple",
"providers": [
{
"provider": "token",
"token": "t0k3n"
},
{
"provider": "header",
"name": "X-Extra-Key",
"value": "k3y"
}
]
}
where
providers
is a list of auth providers to use simultaneously
The 'HMAC' authentication is not built-in one and requires the httpie-hmac
plugin to be installed first. Its only purpose here is to serve as an example of how to invoke third-party authentication plugins from the credentials store.
{
"provider": "hmac",
"auth": "secret:<HMAC_SECRET>"
}
where
auth
is a string with authentication payload passed that is normally passed by a user via--auth
/-a
to HTTPie; each authentication plugin may or may not require one
The plugin supports a bunch of keychains that can be used to pull secrets from secured storage.
Shell provider is nothing more but a mere shell command to execute. The command must return a secret to the plugin via standard output stream. This is a universal approach that can be used to glue together various unsupported password managers and/or keychains.
Example:
{
"keychain": "shell",
"command": "cat ~/path/to/secret | tr -d '\n'"
}
where
command
is a shell command to execute
System provider, as the name suggests, use your system keychain to pull secrets from. It may be KWallet, GNOME Keyring, macOS Keychain or even Windows Credential Locker.
Example:
{
"keychain": "system",
"service": "github",
"username": "ikalnytskyi"
}
where
service
is a service to pull data forusername
is a username for that service to pull data for
Password store provider is a bridge between this plugin and the password store. It invokes pass
on your system and pulls the secret from the first line of the stored record (normally password).
Example:
{
"keychain": "password-store",
"name": "github.com/ikalnytskyi"
}
where
name
is a pass name in terms of the password store
Q: How to learn which credentials have been attached to the request?
A: Unfortunately, due to late credentials binding, it's impossible to learn which credentials have been used by running
http --debug
command. Nevertheless, one can check amends made by auth providers by inspect HTTP headers transmitted within the request by passing-v
argument to HTTPie:http -v
.