Cookies

Cookie support is available in Falcon version 0.3 or later.

Getting Cookies

Cookies can be read from a request via the cookies request attribute:

class Resource(object):
    def on_get(self, req, resp):

        cookies = req.cookies

        if 'my_cookie' in cookies:
            my_cookie_value = cookies['my_cookie']
        # ....

The cookies attribute is a regular dict object.

Tip

The cookies attribute returns a copy of the response cookie dictionary. Assign it to a variable, as shown in the above example, to improve performance when you need to look up more than one cookie.

Setting Cookies

Setting cookies on a response is done via set_cookie().

The set_cookie() method should be used instead of set_header() or append_header(). With set_header() you cannot set multiple headers with the same name (which is how multiple cookies are sent to the client). Furthermore, append_header() appends multiple values to the same header field in a way that is not compatible with the special format required by the Set-Cookie header.

Simple example:

class Resource(object):
    def on_get(self, req, resp):

        # Set the cookie 'my_cookie' to the value 'my cookie value'
        resp.set_cookie('my_cookie', 'my cookie value')

You can of course also set the domain, path and lifetime of the cookie.

class Resource(object):
    def on_get(self, req, resp):
        # Set the maximum age of the cookie to 10 minutes (600 seconds)
        # and the cookie's domain to 'example.com'
        resp.set_cookie('my_cookie', 'my cookie value',
                        max_age=600, domain='example.com')

You can also instruct the client to remove a cookie with the unset_cookie() method:

class Resource(object):
    def on_get(self, req, resp):
        resp.set_cookie('bad_cookie', ':(')

        # Clear the bad cookie
        resp.unset_cookie('bad_cookie')

By default, Falcon sets the secure attribute for cookies. This instructs the client to never transmit the cookie in the clear over HTTP, in order to protect any sensitive data that cookie might contain. If a cookie is set, and a subsequent request is made over HTTP (rather than HTTPS), the client will not include that cookie in the request.

Warning

For this attribute to be effective, your web server or load balancer will need to enforce HTTPS when setting the cookie, as well as in all subsequent requests that require the cookie to be sent back from the client.

When running your application in a development environment, you can disable this default behavior by setting secure_cookies_by_default to False via API.resp_options. This lets you test your app locally without having to set up TLS. You can make this option configurable to easily switch between development and production environments.

Cookies

Getting Cookies

Setting Cookies

The Secure Attribute