User Roles & Metadata
Roles and user information are passed to Platformatic DB from an external authentication service as a string (JWT claims or HTTP headers). We refer to this data as user metadata.
Users can have a list of roles associated with them. These roles can be specified
X-PLATFORMATIC-ROLE property as a list of comma separated role names
(the key name is configurable).
Note that role names are just strings.
Some special role names are reserved by Platformatic DB:
platformatic-admin: this identifies a user who has admin powers
anonymous: set automatically when no roles are associated
If a user has no role, the
anonymous role is assigned automatically. It's possible
to specify rules to apply to users with this role:
In this case, a user that has no role or explicitly has the
cannot perform any operations on the
If a request includes a valid
X-PLATFORMATIC-ADMIN-SECRET HTTP header it is
possible to impersonate a user roles. The roles to impersonate can be specified
by sending a
X-PLATFORMATIC-ROLE HTTP header containing a comma separated list
When JWT or Webhook are set, user role impersonation is not enabled, and the role
is always set as
platfomatic-admin automatically if the
HTTP header is specified.
The roles key in user metadata defaults to
X-PLATFORMATIC-ROLE. It's possible to change it using the
roleKey field in configuration. Same for the
anonymous role, which value can be changed using
User roles and other user data, such as
userId, are referred to by Platformatic
DB as user metadata.
User metadata is parsed from an HTTP request and stored in a
user object on the
Fastify request object. This object is populated on-demand, but it's possible
to populate it explicity with