self_role_add

Give yourself a role that the server marks as self-assignable. Some of these roles have a price and must be paid for through Rotur first.

Request

{
  "cmd": "self_role_add",
  "role": "photography"
}

Field	Type	Required	Description
`role`	string	Yes	Role name. IDs are not accepted. Surrounding spaces are trimmed.
`payment`	string	No	Rotur payment ID for a paid role, up to 128 characters. Ignored when the role is free or already bought.

Response

The reply is a user_roles_get frame, not self_role_add:

{
  "cmd": "user_roles_get",
  "user": "alice",
  "roles": ["user", "photography"],
  "color": "#a78bfa",
  "gradient": []
}

See user_roles_get for the fields.

A free role goes to the end of your role list. A paid role goes to the front, so its color shows on your name.
Every other authenticated connection receives the same frame.
If the role changes which channels you can see, each of your sessions receives a fresh channels_get frame.

The change is recorded in the audit log.

Paid roles

A role with price above 0 costs that much, unless you have manage_roles or have bought it before. To buy one:

Read payee from self_roles_list. If it is "", the server can’t take payments.
Pay payee at least the role’s price through Rotur, from your own account, with the role’s id as the resource.
Send self_role_add with the payment’s ID in payment.

The server finds the payment in the payee’s Rotur earnings and checks it. Once it succeeds, the role counts as bought, so you can remove it and add it again for free.

Permissions

Any member can call it. It is blocked while you are timed out.

The role must be self-assignable, and can’t be owner, admin, or user.
You must already hold every permission the role grants.

Errors

`val`	When
`Role not found`	No role has this name.
`This role is not self-assignable`	The role’s `self_assignable` is `false`.
`This role cannot be self-assigned`	The role is `owner`, `admin`, or `user`.
`Cannot self-assign this role: Cannot assign '<permission>' — you don't have this permission yourself`	The role grants a permission you don’t hold.
`You already have this role`	The role is already in your list.
`Paid roles need a Rotur account`	The role costs something and you’re signed in with a local account.
`This role must be purchased`	The role costs something and `payment` is missing.
`Purchases are not set up on this server`	The server has no payee.
`Could not verify the payment. Try again in a moment.`	The server couldn’t read its Rotur earnings.
`Payment not found`	No payment with this ID was made to the payee.
`That payment was made by another account`	The payment came from a different Rotur account.
`That payment was for something else`	The payment’s resource isn’t this role’s `id`.
`That payment does not cover the role price`	The payment amount is below `price`.
`Failed to assign role '<name>' to yourself`	The server could not write the change to storage.
Validation message	`role` is missing or blank, or `payment` is longer than 128 characters.