Skip to main content
Version: IOTA

Authentication

Usage of the Chronicle API can be protected using JWT by using Chronicle's command-line interface (CLI). Run inx-chronicle --help to learn about all available options under the API section.

All JWT interactions should be performed via HTTPS.

Public Routes​

When a route is configured to be public, it can be accessed freely without providing a JWT. Thus, you should take care when specifying these routes, as a mis-configured route can open the application up to attacks. The only accepted special character is the wildcard (*), which will be converted to a regex .* and match against the original URI.

For instance, a request GET https://localhost:XXXX/api/core/v2/milestones/by-index/10000 will check the set of public routes against the segment /api/core/v2/milestones/by-index/10000.

Matching strings include:

  • /api/*
  • /api/core/*/milestones/by-index/*
  • *10000

Non-matching strings include:

  • /core/v2/milestones/by-index/*
  • /api/core/v2/milestones/by-index
  • /api/core/v1/*

If JWT is used, these routes should be as specific as possible to avoid accidentally exposing unintended routes.

Keys​

Chronicle uses an EdDSA secret key to create tokens, which can be generated by the application at startup or provided as an identity file using the identity_path config. Currently, this file must be a PKCS8 secret key (RFC 5208) PEM file. The location of this file can also optionally be specified using the IDENTITY_PATH env variable, which will be overridden by the config file value. If no such file is provided, a secret key is randomly generated for use while the application is running.

Generating a Token​

A special route at the root (/login) is provided for generating a new token. This token will use the password config as well as the jwt_expiration and the secret key. This token can be manually generated by the client, if desired, by using the same identity and claims.

Static claims used by Chronicle are:

  • iss: "chronicle"
  • aud: "api"

The sub (subject) claim is filled using a unique UUID, however it is not currently stored or validated by Chronicle.

Providing a Token​

To provide a token when making a request, include it in an Authorization header using the Bearer authentication scheme.