Skip to main content

Authenticated and encrypted API tokens using modern crypto

Project description

Branca Tokens for Python

Authenticated and encrypted API tokens using modern crypto.

Latest Version Software License Build Status Coverage


Branca is a secure easy to use token format which makes it hard to shoot yourself in the foot. It uses IETF XChaCha20-Poly1305 AEAD symmetric encryption to create encrypted and tamperproof tokens. Payload itself is an arbitrary sequence of bytes. You can use for example a JSON object, plain text string or even binary data serialized by MessagePack or Protocol Buffers.

Although not a design goal, it is possible to use Branca as an alternative to JWT.


Install the library using pip. Note that you also must have libsodium installed.

$ brew install libsodium
$ pip install pybranca


The payload of the token can be anything, like a simple string.

from branca import Branca

branca = Branca(key="supersecretkeyyoushouldnotcommit")

token = branca.encode("Hello world!")
payload = branca.decode(token)


# 87xqn4ACMhqDZvoNuO0pXykuDlCwRz4Vg7LS3klfHpTiOUw1ramOqfWoaA6bvsGwOQ49MDFOERU0T
# b'Hello world!'

For more complicated data structures JSON is an usual choice.

import json
from branca import Branca

branca = Branca(key="supersecretkeyyoushouldnotcommit")

string = json.dumps({"scope" : ["read", "write", "delete"]})

token = branca.encode(string)
payload = branca.decode(token)


# 6AlLJaBIFpXbwKTFsI3xXsk4se8YsdEKOtxYwtYDQHpoqabwZzmxAUS99BLxBJpmfJqnJ9VvzJYO1FXfsX78d0YsvTe43opYbUPgUao0EGV5qBli
# b'{"scope": ["read", "write", "delete"]}'
# {'scope': ['read', 'write', 'delete']}

By using MessagePack you can have more compact tokens.

import msgpack
from branca import Branca

branca = Branca(key="supersecretkeyyoushouldnotcommit")

packed = msgpack.dumps({"scope" : ["read", "write", "delete"]})

token = branca.encode(packed)
payload = branca.decode(token)

print(msgpack.loads(payload, raw=False))

# 3iJOQqw5CWjCRRDnsd7Jh4dfsyf7a4qbuEO0uT8MBEvnMVaR8rOW4dFKBVFKKgxZkVlNchGJSIgPdHtHIM4rF4mZYsriTE37
# b'\x81\xa5scope\x93\xa4read\xa5write\xa6delete'
# {'scope': ['read', 'write', 'delete']}


The MIT License (MIT). Please see License File for more information.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pybranca, version 0.4.0
Filename, size File type Python version Upload date Hashes
Filename, size pybranca-0.4.0.tar.gz (5.9 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page