httpie-credential-store 1.0.0

Usage

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 using id 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 creds or -A credential-store to http executable.

$ http -A creds https://api.github.com

Optionally, you can provide an ID of the credential record to use by passing -a argument.

$ http -A creds -a bots https://api.github.com

Authentication providers

HTTPie Credential Store comes with the following authentication providers out of box.

{
  "provider": "basic",
  "username": "ikalnytskyi",
  "password": "p@ss"
}

{
  "provider": "digest",
  "username": "ikalnytskyi",
  "password": "p@ss"
}

{
  "provider": "token",
  "token": "t0k3n",
  "scheme": "JWT"
}

{
  "provider": "header",
  "name": "X-Extra-Key",
  "value": "k3y"
}

{
  "provider": "multiple",
  "providers": [
    {
      "provider": "token",
      "token": "t0k3n"
    },
    {
      "provider": "header",
      "name": "X-Extra-Key",
      "value": "k3y"
    }
  ]
}

Keychain providers

The plugin supports a bunch of keychains that can be used to pull secrets from secured storage.

{
  "keychain": "shell",
  "command": "cat ~/path/to/secret | tr -d '\n'"
}

{
  "keychain": "system",
  "service": "github",
  "username": "ikalnytskyi"
}

{
  "keychain": "password-store",
  "name": "github.com/ikalnytskyi"
}

FAQ

• 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.