Authenticated and encrypted API tokens using modern crypto.

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.

It is possible to use Branca as an alternative to JWT.

Add this line to your application's Gemfile, Note that you also must have libsodium installed.

gem 'branca-ruby', '~> 1.0.1'

You must be configure secret_key and ttl using this.

require 'branca'

Branca.configure do |config|
  config.secret_key = 'supersecretkeyyoushouldnotcommit'.b
  config.ttl = 86_400 # in seconds
end

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

Branca.encode('with string')

# 1y48BiLKOcB4N8xjazwFpas3DwOovXzu6vtbiUr4bDAGLaVyFjIN5Xwz5p3qvNYsi5kWjk7ilgnS

or JSON stringified

Branca.encode(JSON.generate({ permissions: [] }))

# ATkzLjriA1ijbBcuZOJ1zMR0z5oVXDGDVjUWwrqJWszynAM4GLGiTwZnC6nUvtVIuavAVCMbwcsYqlYKejOI4

You can also pass timestamp to encode

Branca.encode('with string', Time.now.utc)

# 1y48BiV0jaalTYiARPdbm52IKgGEhfwq8DlP9ulKBx8LMLFrjNKe88vIGIUxsWzybIwBhmVvIam5

If you branca token isnt expired. You will receive something like this

decode = Branca.decode('1y48BiV0jaalTYiARPdbm52IKgGEhfwq8DlP9ulKBx8LMLFrjNKe88vIGIUxsWzybIwBhmVvIam5')

# <Branca::Decoder:0x00007fde4e3e6398 @message="with string", @timestamp=2020-10-27 03:44:03 UTC>

decode.message
# "with string"

Token is expired, will receive exception Branca::ExpiredTokenError

Invalid Version, will receive exception Branca::VersionError

We have a long list of valued contributors. Check them all at: https://github.com/thadeu/branca-ruby.