Grant User Role

Audience: Low-code Engineers

Skill Prerequisites: Actions, Tokens, User management

Adds one or more users to one or more security roles in the current portal. You can make the role valid forever, for a number of days, or between two dates.

By default, the role goes to the current user and to every user in the context's list of users. In a form, the current user is usually the logged-in user. Use Load User or Load Users from SQL to pick other users, or enter a user in To User to grant the role to that user only.

If a user already has the role, it's granted again with the new dates. For how roles are used in Plant an App, see Roles.

Typical Use Cases

• Give a new user a role right after User Registration
• Give access to a paid area for a number of days, for example a 30-day trial
• Grant a role to a group of users loaded with Load Users from SQL
• Grant a role to a user picked by ID, username or email, for example from a Listing row

Don't use it to

• Create a role. Use Create Role instead.
• Take a role away. Use Revoke User Role instead.
• Let users pick their own role in a public form. See Considerations.

Related Actions

Action Name	Description
Revoke User Role	Removes roles from the current user and from every user in the list.
Load User	Loads users into the list and makes the last one the current user.
Load Users from SQL	Adds the users returned by a SQL query to the list.
Change User	Changes the current user without adding it to the list.
User Registration	Creates a user, who then becomes the current user.
Create Role	Creates a new role.
Update Role	Changes a role's settings.
Delete Role	Deletes a role.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
Role	The role to grant, picked from the portal's roles. In expression mode, enter role IDs or role names, separated by commas, for example [RoleId].	Yes	empty	No
Other Role Names	More roles to grant, as role names or role IDs, separated by commas, semicolons or new lines, for example Subscribers, Newsletter. They're granted together with Role.	Yes	empty string	No
To User	The user to grant the roles to, as a user ID, email address or username, for example [Email]. Leave it empty to grant the roles to the current user and to every user in the list.	Yes	empty string	No
Role Validity	How the start and expiry dates are set. See Role validity.	No	For a number of days (starting now)	No
Role Expiration (days)	The number of days the role is valid, for example 30. Leave it empty for no expiry. Shown for For a number of days (starting now) and For a number of days.	Yes	empty string	No
Start Date	The date the role starts. Shown for Date interval and For a number of days.	No	empty	No
Expire Date	The date the role expires. Shown for Date interval.	No	empty	No
Start Date Token	The start date, for example [StartDate]. Shown for Date interval (with tokens).	Yes	empty string	No
Expire Date Token	The expiry date, for example [EndDate]. Shown for Date interval (with tokens).	Yes	empty string	No
Extension Days	The number of days to add to the current expiry date. Shown for Extend a role validity period. See Role validity.	Yes	empty string	No

You need at least one role in Role or Other Role Names. If none of them match a role, the action does nothing.

Output Parameters Reference

This action has no output parameters.

Which users get the role

To User	Users who get the role
Filled in	Only that user. The current user and the list are ignored.
Empty	The current user, plus every user in the list.

To User is looked up on the current portal, in this order:

1. If it's a number, it's treated as a user ID.
2. Otherwise, it's matched against email addresses.
3. If no email matches, it's matched against usernames.

If no user is found, the action fails with Could not find a user with the provided identifier.

When To User is empty and there's no current user and nothing in the list, for example in a public form, nothing happens and there's no error.

Role validity

Role Validity	Start	Expiry
For a number of days (starting now)	Right away.	Today plus Role Expiration (days). Empty means no expiry.
For a number of days	Start Date.	Start Date plus Role Expiration (days). If Role Expiration (days) is empty, the start date is ignored too: the role starts right away and never expires.
Date interval	Start Date.	Expire Date.
Date interval (with tokens)	Start Date Token.	Expire Date Token.
Extend a role validity period	See below.	See below.

• Only the date is kept. Times are dropped, and "today" is the server's date.
• Token dates should be in ISO format, for example 2026-12-31 or the value of [DateTime:Utc|o]. If a token value can't be read as a date, the action fails. An empty token means no start date or no expiry.
• If Role Expiration (days) isn't a whole number, the action fails.
• The action doesn't check that the start date is before the expiry date.

Extend a role validity period is meant to add Extension Days to the user's current expiry date, or to grant the role for that many days if the user doesn't have it. A negative number removes days. Extension Days must be a whole number other than 0, or the action fails.

warning

In this version, Extend a role validity period doesn't work as described. If the user doesn't have the role yet, the action fails. If the user has it, the new start and expiry dates are swapped, so the role may stop working. Use one of the other options instead.

Considerations

• There's no permission check in the action. Anyone who can run it can grant any role, including Administrators. Only put it where you control who runs it.
• Don't build roles or users from values the user sends. If Role, Other Role Names or To User use tokens from form fields, the query string or an API request, a user can change them and grant themselves, or anyone else, any role. In a public form, hard-code the roles and leave To User empty.
• Granting again replaces the dates. If the user already has the role, the old start and expiry dates are replaced by the new ones. For example, granting a role for 30 days to a user who has it with no expiry makes it expire in 30 days. Granting with no expiry makes a temporary role permanent.
• Check who's in the list. With To User empty, every loaded user gets the role, plus the current user. Users loaded earlier in the same run are still in the list. See Load User.
• The current user also gets the role. In a form, that's usually the person who clicked. To grant a role only to other users, use To User, or change the current user first with Load User.
• Numbers are always role IDs. In Other Role Names, a value like 2024 is looked up as a role ID, not a role name. Role names that don't exist are skipped without an error.
• Roles are from the current portal. Only roles of the current portal can be granted.
• No email is sent. The user isn't notified.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Grant a 30-day trial role to the current user

This action grants the role with ID 7 to the current user, starting today and expiring in 30 days.

{
    "Title": "Grant User Role",
    "ActionType": "GrantUserRole",
    "Description": "Grant the trial role for 30 days",
    "Parameters": {
        "RoleId": {
            "Expression": "",
            "Value": "7",
            "IsExpression": false,
            "Parameters": {}
        },
        "RoleNames": "",
        "GrantToUserIdOrName": "",
        "DateSelectionMode": {
            "Expression": "",
            "Value": "OffsetFromNow",
            "IsExpression": false,
            "Parameters": {}
        },
        "ExtensionDays": "",
        "StartDate": {
            "Date": ""
        },
        "StartDateToken": "",
        "ExpireDate": {
            "Date": ""
        },
        "ExpireDateToken": "",
        "RoleExpiration": "30"
    }
}

2. Grant roles by name to a specific user

This action grants the Subscribers and Newsletter roles, with no expiry, to the user whose email is in the Email token. It only runs when the Plan token is Premium. Because it changes another user, use it only where trusted users can run it.

{
    "Title": "Grant User Role",
    "ActionType": "GrantUserRole",
    "Description": "Grant premium roles to the selected user",
    "Condition": "\"[Plan]\" == \"Premium\"",
    "Parameters": {
        "RoleId": {
            "Expression": "",
            "Value": "",
            "IsExpression": false,
            "Parameters": {}
        },
        "RoleNames": "Subscribers, Newsletter",
        "GrantToUserIdOrName": "[Email]",
        "DateSelectionMode": {
            "Expression": "",
            "Value": "OffsetFromNow",
            "IsExpression": false,
            "Parameters": {}
        },
        "ExtensionDays": "",
        "StartDate": {
            "Date": ""
        },
        "StartDateToken": "",
        "ExpireDate": {
            "Date": ""
        },
        "ExpireDateToken": "",
        "RoleExpiration": ""
    }
}

3. Grant a role between two dates from tokens

This action grants the Event Attendees role to the current user from the date in the EventStart token to the date in the EventEnd token, for example 2026-10-01 and 2026-10-03.

{
    "Title": "Grant User Role",
    "ActionType": "GrantUserRole",
    "Description": "Grant the role for the event dates",
    "Parameters": {
        "RoleId": {
            "Expression": "",
            "Value": "",
            "IsExpression": false,
            "Parameters": {}
        },
        "RoleNames": "Event Attendees",
        "GrantToUserIdOrName": "",
        "DateSelectionMode": {
            "Expression": "",
            "Value": "DateTokens",
            "IsExpression": false,
            "Parameters": {}
        },
        "ExtensionDays": "",
        "StartDate": {
            "Date": ""
        },
        "StartDateToken": "[EventStart]",
        "ExpireDate": {
            "Date": ""
        },
        "ExpireDateToken": "[EventEnd]",
        "RoleExpiration": ""
    }
}

Revised 09/28/2026