Seald: documentation

# JSON Web Tokens

As a security measure, in order to avoid misuse of your encryption quotas, your server must allow identity creation and anonymous encryptions using JSON Web tokens.

This feature replaces the now deprecated User License Tokens.

# Creating a JWTSecret

Once the JWTSecret is created, you will need to retrieve this JWTSecret and its JWTSecretId to enable your server to create JSON Web Tokens.

Each JWTSecret has permissions. For more details, see permissions.

TIP

JWTSecret is, as the name implies, secret. Please take appropriate measures to store it securely.

However, JWTSecretId is not secret.

# Via the dashboard

When creating your dashboard account, a JWT secret including all permissions (permission: -1) is automatically created. This is displayed on the homepage.

To generate another JWT Secret, login to your admin dashboard and follow these steps:

  • Go to the settings, JWT secrets tab.
  • Click on create a secret.
  • Select the desired permissions.
  • Confirm the creation of the secret.

Once the secret is created, retrieve its ID, JWTSecretId, and its value: JWTSecret.

# Programmatically

To create a JSON Web Token, you first need a JWTSecret.

You can create, list, and delete JWTSecret, which allow to create JSON Web Tokens for your team, on the DashboardAPI.

In order to create a JWTSecret, you can make a POST /dashboardapi/v2/jwtsharedsecret/, with the request body:

{
  "permissions": Array<Permission>
}

# Code example

Example request to create a JWTSecret:

curl -X POST https://dashboard.seald.io/dashboardapi/v2/jwtsharedsecret/ \
  -H 'X-DASHBOARD-API-KEY: YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{"permissions": [1]}'

Example response:

{
  "id": "32266d8c-2085-490a-8ef5-259ea35e1501", // UUID : JWTSecretId
  "created": "2021-11-09T10:49:09.490338Z", // Timestamp ISO
  "shared_secret": "c9kijQo1kJgieXZ9TAHFj9R0TgHb4bgLhDnWWRgjq4TmBzUdSB5mzuOcBb0gQMSi", // String : JWTSecret
  "permissions": [ 1 ] // Array<Permission>
}

# Adding a userId

You can add a userId to a SDK identity. It is a string that specifies a user uniquely for your application. You can choose any unique identifier. Depending on the user model in your application, you can for example choose: the username, their email address, their internal ID in your application, ...

WARNING

The userId is stored in clear text in our database. In order to minimize the data that Seald stores about your users, it is not recommended to use an email address or any other personal identifying information. The optimal is to use a UUID.

# JSON Web Token permissions

Each JWTSecret has permissions, and it can assign any or all of the permissions it has to each JSON Web Token it creates.

Permission are integers. Possible values are as follows:

  • PERMISSION_ALL = -1: all permissions.
  • PERMISSION_ANONYMOUS_CREATE_MESSAGE = 0: allows creating JSON Web Tokens which can anonymously create messages.
  • PERMISSION_ANONYMOUS_FIND_KEYS = 1: allows creating JSON Web Tokens which can retrieve the recipients' encryption keys.
  • PERMISSION_ANONYMOUS_FIND_SIGCHAIN = 2: allows creating JSON Web Tokens which can retrieve the recipients' SigChain. Unused.
  • PERMISSION_JOIN_TEAM = 3 : allows creating JSON Web Tokens which can add an SDK identity to your team.
  • PERMISSION_ADD_CONNECTOR = 4 : allows creating JSON Web Tokens which can add a custom userId to an SDK identity.

# Creating a JSON Web Token

The JSON Web Token, or JWT, is created with the JWTSecret and its JWTSecretId: it has the JWTSecretId as iss, and is signed with the JWTSecret with the HS256 algorithm.

Its payload is:

Name Type Use Description
iss string Always "Issuer" : the JWTSecretId
iat? number Always "Issued at" : timestamp (in seconds) of the JWT creation. Optional. If defined, the JWT expires 10 min after creation. If not, it does not expire.
jti? number Always "JWT ID" : unique nonce. Must never be re-used. Optional. If defined, the JWT is usable only once. If not, it is usable until its potential expiration.
scopes? Array<Permission> Always List of this JWT's permissions. Optional. Must be a subset of the JWTSecret's permissions. If defined, the JWT is limited to these permissions only. If not, it has all the permissions assigned to the creating JWTSecret.
recipients? Array<string> Anonymous encryption List of sealdIds of recipients for whom this JWT is authorized to perform operations.
owner? string Anonymous encryption Optional for retrieving recipient keys. Necessary for message creation. sealdId of the user who will own the created messages.
join_team? boolean Identities Allow the identity to join your team. Each identity can only be in one team at a time.
connector_add? { value: connectorValue, type: 'AP' } Identities Allows the addition of a custom identifier to an identity. The value must be of the form custom-string@AppId.

# Code example

Example of creating a JWT for signup in Node.JS:

Example of creating a JWT to add a custom userId in Node.JS:

Example of creating a JWT for anonymous encryption in Node.JS:

Example of creating a JWT in Python:

← Presentation →