Skip to main content

Token format

Authentication uses JSON Web Tokens, a standard method for representing claims securely between two parties. See more info here and a list of JWT libraries here.

Required claims

user_id

A valid authentication JWT must contain a user_id claim. This must be a non-empty string, which should correspond to the primary key UUID of the authenticated app user.

Validated claims

If you are using insecure mode any other claims are optional and unvalidated.

If you are using secure mode you must also provide valid iat and exp claims. Plus, if you include values for iss and/or aud claims in your configuration, those will also be validated.

Additional data

Additional claims will be available on the auth context in your DDLX rules. It's conventional to put additional data under the data key.

So if, in your auth JWT, you provide the following claims:

{
"user_id": "000",
"data": {
"foo": "bar"
}
}

In your DDLX statements you can lookup the value for the key foo as follows:

auth.data.foo    // 'bar'

Custom claim namespace

If you can't put claims that are specific to Electric at the root of your token, it is possible to define a custom namespace to put those claims under. For example, if you start Electric with AUTH_JWT_NAMESPACE=https://myapp.dev/jwt/claims, your JWTs should look as follows:

{
"https://myapp.dev/jwt/claims": {
"user_id": "000",
"data": {
"foo": "bar"
}
}
}

You'll still be able to access user_id and additional data in your DDLX statements the usual way:

auth.user_id     // '000'
auth.data.foo // 'bar'