The :auth header is composed of a base plugin, and two derived plugins.
The :auth plugin manages the generation of tokens to be included in the “authorization” header.
It supports the following options:
:auth_header_value: the token to use as a string, or a callable which returns a string when called.:auth_header_type: the authentication type to use in the "authorization" header value (i.e. "Bearer", "Digest"…):generate_auth_value_on_retry: callable which returns whether the request should regenerate the :auth_header_value when the request is retried (this option will only work if the session also loads the retries plugin).http = HTTPX.plugin(:auth)
# authorization: AUTH-TOKEN
http.authorization("AUTH-TOKEN").get("https://api.myapp.com/resources")
# same as
http.get("https://api.myapp.com/resources", auth_header_value: "AUTH-TOKEN")
# authorization: Bearer AUTH-TOKEN
http.bearer_auth("AUTH-TOKEN").get("https://api.myapp.com/resources")
# same as
http.get("https://api.myapp.com/resources", auth_header_value: "AUTH-TOKEN", auth_header_type: "Bearer")
# generation of ephemeral tokens managed by separate function
authenticated = http.authorization { generate_ephemeral_token }
# authorization: random-e409uer
authenticated.get("https://api.myapp.com/resources")
# authorization: random-e409uer (same session reuses the same token)
authenticated.get("https://api.myapp.com/resources")
# you can reset the token, so that a new one is generated
authenticated.reset_auth_header_value!
# authorization: random-12eu12e
authenticated.get("https://api.myapp.com/resources")
# authorization: random-2j3r3ja (new session creates a new token)
http.authorization { generate_ephemeral_token }.get("https://api.myapp.com/resources")
# same as
http.get("https://api.myapp.com/resources", auth_header_value: -> (req) { generate_ephemeral_token })
# `bearer_auth` can also be used with a block:
# authorization: Bearer random-54f5e6fg6
http.bearer_auth { generate_ephemeral_token }.get("https://api.myapp.com/resources")
# when used with the `:retries` plugin, the evaluation of the `:generate_auth_value_on_retry` callable will cause the session token to be regenerated:
authenticated = http.plugin(:retries).with(
auth_header_value: ->(req) { generate_ephemeral_token },
generate_auth_value_on_retry: ->(res) { res.is_a?(HTTPX::Response) && res.status == 401 }
)
# authorization: random-e409uer
authenticated.get("https://api.myapp.com/resources") #=> 200
authenticated.get("https://api.myapp.com/resources") #=> same token, 200
# 2 hours later, after the token expires...
authenticated.get("https://api.myapp.com/resources")
# authorization: random-e409uer, 401
# retry, authorization: random-238r7yr32, 200
The :basic_auth plugin can create an HTTP Basic Auth compatible header based on a username and password.
http = HTTPX.plugin(:basic_auth)
http.basic_auth("user", "pass").get("https://api.myapp.com/resources")
The :digest_auth plugin provides an API to authenticate requests using HTTP Digest access authentication
http = HTTPX.plugin(:digest_auth)
http.digest_auth("user", "pass").get("https://api.myapp.com/resources")
Note: due to the required extra-roundtrip, requests will be executed one at a time.
The :ntlm_auth plugin can provides an API to authenticate requests using NTLM auth
http = HTTPX.plugin(:ntlm_auth)
http.ntlm_auth("user", "pass", "Domain").get("https://api.myapp.com/resources")
Next: Follow Redirects