Permissions

Every request to the EasyPoll API is authorized twice: the API key identifies who you are, and the EasyPoll permissions decide what that user is allowed to do in a specific server.

Permissions are stored as a bitfield. Each permission is a single bit, and the API always transports the combined value as a decimal string, for example "268435456". Strings are used because the value can grow beyond what a JSON number safely represents.

Where Permissions Come From

An API key acts on behalf of the user who created it. For every request, EasyPoll resolves the permissions of that user for the server the request targets:

• Server Owner, members with Administrator and members with Manage Server always receive full access. They are not affected by the permissions below.
• All other members get the permissions of their Discord roles. If several of their roles have EasyPoll permissions, the bitfields are combined with a bitwise OR.
• Server permissions are configured in the EasyPoll Dashboard under Settings => Dashboard Permissions, or through PATCH /guilds/{guildId}/roles/{roleId}. See Dashboard Permissions for the user facing description of the same system.

If the resolved permissions do not contain the permission an endpoint requires, the request is rejected with 403 Forbidden.

info

Server members who are not in the server the request targets, or who cannot be resolved at all, are also answered with 403 Forbidden. The API does not distinguish between "not allowed" and "not visible" for these cases.

warning

MANAGE_GUILD_ROLES only covers the voting weight of a role. Changing the permissions of a role through PATCH /guilds/{guildId}/roles/{roleId} additionally requires the acting user to be the Server Owner or to have Administrator or Manage Server in Discord. The @everyone role cannot be given EasyPoll permissions at all.

Full Access

Permission	Bit	Value
FULL_ACCESS	0	1

FULL_ACCESS grants everything, including permissions that are added in the future. It is what the Server Owner, Administrator and Manage Server get, and it can also be granted to a role.

warning

GET /guilds/{guildId} returns the effective permissions of the requesting user in the userPermissions field. When the user has full access, this field is "1" (FULL_ACCESS) instead of a fully populated bitfield. Always check for FULL_ACCESS first before testing individual permissions, otherwise a check like "may this user manage polls" wrongly returns false for server administrators.

Permission Flags

The following permissions apply to a single server and are the ones you can grant to a role.

Server

Permission	Bit	Value	Description
VIEW_GUILD	17	131072	Read the server, its settings, limits, polls and scheduled polls
MANAGE_GUILDS	18	262144	Change the server settings, for example language, colors, events and logging

Roles

Permission	Bit	Value	Description
LIST_GUILD_ROLES	19	524288	Read the list of roles with weights and permissions
VIEW_GUILD_ROLE	20	1048576	Read a single role
MANAGE_GUILD_ROLES	21	2097152	Change the voting weight of a role

Restrictions

Permission	Bit	Value	Description
LIST_GUILD_RESTRICTIONS	22	4194304	Read all restrictions of the server
VIEW_GUILD_RESTRICTION	23	8388608	Read a single restriction
MANAGE_GUILD_RESTRICTIONS	24	16777216	Create and delete restrictions

Audit Log

Permission	Bit	Value	Description
LIST_GUILD_AUDIT_LOG	25	33554432	Read the audit log of the server and of single polls

Polls

Permission	Bit	Value	Description
VIEW_POLL	28	268435456	Read a single poll
MANAGE_POLLS	29	536870912	Create, update, publish, close, reopen and delete polls

Poll Answers

Permission	Bit	Value	Description
LIST_POLL_ANSWERS	30	1073741824	Read all answers of a poll
VIEW_POLL_ANSWER	31	2147483648	Read a single answer
MANAGE_POLL_ANSWERS	32	4294967296	Create, update and delete answers

Poll Votes

Permission	Bit	Value	Description
LIST_POLL_VOTES	33	8589934592	Read all votes of a poll or answer
VIEW_POLL_VOTE	34	17179869184	Read a single vote
MANAGE_POLL_VOTES	35	34359738368	Delete votes

Working With Bitfields

Because permissions are transported as strings and can exceed Number.MAX_SAFE_INTEGER, parse them into a big integer type before doing any arithmetic.

const FULL_ACCESS = 1n;
const MANAGE_POLLS = 1n << 29n;

const guild = await fetch('https://easypoll.com/api/v1/guilds/552156123734474762', {
	headers: { Authorization: `Bearer ${apiKey}` }
}).then((res) => res.json());

const permissions = BigInt(guild.userPermissions ?? '0');

const has = (permission) =>
	(permissions & FULL_ACCESS) === FULL_ACCESS ||
	(permissions & permission) === permission;

if (has(MANAGE_POLLS)) {
	// The user may create, edit and close polls in this server
}

FULL_ACCESS = 1
MANAGE_POLLS = 1 << 29

permissions = int(guild.get("userPermissions") or "0")

def has(permission: int) -> bool:
    return permissions & FULL_ACCESS == FULL_ACCESS or permissions & permission == permission

Granting and revoking a permission works the same way, for example when updating a role:

const LIST_POLL_VOTES = 1n << 33n;

let permissions = BigInt(role.permissions);

permissions |= LIST_POLL_VOTES; // grant
permissions &= ~LIST_POLL_VOTES; // revoke

await fetch(
	`https://easypoll.com/api/v1/guilds/${guildId}/roles/${roleId}`,
	{
		method: 'PATCH',
		headers: {
			Authorization: `Bearer ${apiKey}`,
			'Content-Type': 'application/json'
		},
		body: JSON.stringify({ permissions: permissions.toString() })
	}
);

A permissions value that contains an unknown bit is rejected with 400 Bad Request.

Discord Permissions vs. EasyPoll Permissions

Two different bitfields appear in the API responses, and they are not interchangeable:

Field	Meaning
permissions on a guild in GET /users/@me/guilds and GET /guilds/{guildId}	The Discord permissions of the user in that server
userPermissions on GET /guilds/{guildId}	The effective EasyPoll permissions of the user for that server
permissions on a role	The EasyPoll permissions granted to that role

The EasyPoll permissions on this page are the ones that control access to the API. The Discord permissions are passed through for convenience, for example to detect administrators in your own interface.