Authentication¶
This section covers how to do authentication with Uplink.
In v0.4, we added the auth
parameter to the
uplink.Consumer
constructor which allowed for
sending HTTP Basic Authentication with all requests.
In v0.9, we added more auth methods which can be used in the
auth
parameter of the uplink.Consumer
constructor. If you are using an uplink-based API library,
the library might extend these methods with additional
API-specific auth methods.
Some common auth methods are described below, but for a complete list of auth methods provided with Uplink, see the Auth Methods reference.
Basic Authentication¶
It’s simple to construct a consumer that uses HTTP Basic Authentication with all requests:
github = GitHub(BASE_URL, auth=("user", "pass"))
Proxy Authentication¶
If you need to supply credentials for an intermediate proxy
in addition to the API’s HTTP Basic Authentication, use
uplink.auth.MultiAuth
with uplink.auth.ProxyAuth
and uplink.auth.BasicAuth
.
from uplink.auth import BasicAuth, MultiAuth, ProxyAuth
auth_methods = MultiAuth(
ProxyAuth("proxy_user", "proxy_pass"),
BasicAuth("user", "pass")
)
github = GitHub(BASE_URL, auth=auth_methods)
Other Authentication¶
Often, APIs accept credentials as header values (e.g., Bearer tokens) or query parameters. Your request method can handle these types of authentication by simply accepting the user’s credentials as an argument:
@post("/user")
def update_user(self, access_token: Query, **info: Body):
"""Update the user associated to the given access token."""
If several request methods require authentication, you can persist the token
through the consumer’s session
property:
class GitHub(Consumer):
def __init__(self, base_url, access_token):
super(GitHub, self).__init__(base_url=base_url)
self.session.params["access_token"] = access_token
...
As of v0.9, you can also supply these tokens via the auth
parameter of the uplink.Consumer
constructor. This is
like adding the token to the session (above) so that the token is
sent as part of every request.
from uplink.auth import ApiTokenParam, ApiTokenHeader, BearerToken
# Passing an auth token as a query parameter
token_auth = ApiTokenParam("access_token", access_token)
github = GitHub(BASE_URL, auth=token_auth)
# Passing the token as a header value
token_auth = ApiTokenHeader("Access-Token", access_token)
github = GitHub(BASE_URL, auth=token_auth)
# Passing a Bearer auth token
bearer_auth = BearerToken(access_token)
github = GitHub(BASE_URL, auth=bearer_auth)
Using Auth Support for Requests and aiohttp¶
As we work towards Uplink’s v1.0 release, improving built-in support for other types of authentication is a continuing goal.
With that said, if Uplink currently doesn’t offer a solution for you authentication needs, you can always leverage the available auth support for the underlying HTTP client.
For instance, requests
offers out-of-the-box support for
making requests with HTTP Digest Authentication, which you can leverage
like so:
from requests.auth import HTTPDigestAuth
client = uplink.RequestsClient(cred=HTTPDigestAuth("user", "pass"))
api = MyApi(BASE_URL, client=client)
You can also use other third-party libraries that extend auth support for the underlying client. For instance, you can use requests-oauthlib for doing OAuth with Requests:
from requests_oauthlib import OAuth2Session
session = OAuth2Session(...)
api = MyApi(BASE_URL, client=session)