Grant a role

POST /v1/roles/grant · requires roles:manage

Body parameters

Returns

Example

curl -X POST https://ceejay.communitystudios.xyz/api/v1/roles/grant \
  -H "Authorization: Bearer $CEEJAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "discordId": "409876543210987654",
    "roleId": "982371004827100394"
  }'

The TypeScript example uses ceejay.roles.grant from the TypeScript SDK. It returns the data of the response below.

{
  "success": true,
  "data": {
    "discordId": "409876543210987654",
    "roleId": "982371004827100394",
    "action": "granted",
    "duplicate": false
  }
}

How it works

CEEJAY looks up the role in your server, then asks Discord to add it to the member and responds once Discord has done so. A member who already has the role is not an error. The call changes the role and nothing else: it grants no XP or currency, and it sends no webhook event of its own.

The change shows in your server's audit log in Discord, made by the CEEJAY bot, with the reason API key: followed by the name of the key that made the call.

Roles a key can change

A key can grant or revoke an ordinary role of its own server, and no other. The role is checked before Discord is asked to change anything:

• A role that is not in your server returns 404 with the code role_not_found.
• The @everyone role returns 403 with the code role_not_allowed.
• A role that Discord or another app manages, such as a bot's own role or the server booster role, returns 403 with the code role_not_allowed.
• A role that can moderate or manage the server returns 403 with the code role_not_allowed. That is a role with any of these permissions: Administrator, Kick Members, Ban Members, Timeout Members, Manage Server, Manage Channels, Manage Roles, View Audit Log, Manage Messages, Manage Nicknames, Manage Webhooks, Manage Expressions, Manage Events, Manage Threads, Mute Members, Deafen Members or Move Members.
• A role that can mention everyone returns 403 with the code role_not_allowed, in a server whose @everyone role cannot. That is a role with the Mention @everyone, @here, and All Roles permission. Where the @everyone role has that permission itself, every member can already mention everyone, a role that also has it adds nothing, and it is not rejected. Discord grants @everyone this permission in a new server, and a new role starts with the permissions of @everyone, so in a server that never disabled it most roles have it.
• A bot master role returns 403 with the code role_not_allowed. That is a role your community added under Settings → General → Team Management, in Additional Bot Master Roles. Anyone with this role has full access to the CEEJAY dashboard, whatever its Discord permissions are: see Team management.

List roles shows, for every role in your server, whether a key may change it and, if not, why. A role that has moderation permissions only through channel permission overwrites cannot be seen from the role list.

CEEJAY reads your server's role list from Discord and caches it for up to a minute. A role you created a moment ago is found immediately. A change to a role's permissions can take up to a minute to apply. When the list cannot be read, the call returns 503 with the code roles_unavailable and nothing is changed.

The bot master roles are read on every call and never cached, so a role your community adds there is rejected immediately. When they cannot be read, the call returns 503 with the code dashboard_roles_unavailable, and nothing is changed.

Keep a key with roles:manage on your own backend all the same, and never in a game client.

Retrying safely

Send an idempotencyKey with every call you might need to retry, such as after a timeout. It is a string of 1 to 128 characters that you choose, sent in the JSON body: an Idempotency-Key header is not read.

• Retrying with the same key returns the original response. When the same request is sent again with its key, CEEJAY returns the original response, with duplicate: true and the header Idempotent-Replayed: true.
• Each key is tied to one request payload. The same request means the same member and role. Two requests for one event need two keys, for example match-9:coins and match-9:xp. A key that was used for a different request, here or on any other request of the API, returns 409 with the code idempotency_key_reused, and nothing is changed.
• A rejected request does not use up the key. A call that was rejected can be retried with the same key once the cause is fixed.
• A key belongs to the API key that sent it. Another API key of your community can send the same text, and it is a different key.
• Keys are retained for 30 days. Use a value you can regenerate after a crash, such as an order ID or a match ID.
• On an instance that does not support idempotency keys yet, a call that sends one returns 503 with the code idempotency_unavailable, and nothing is changed. Community details reports whether keys are supported, under features.retryKeys. idempotency_key is not accepted on this endpoint; use idempotencyKey.
• Without a key, a retried call is a new call.

Granting a role is idempotent, so when a first request was started more than a minute ago and never finished, a retry with the same key makes the change again and returns normally. The request is also safe to repeat without a key.

Errors

Discord's own rate limit returns 429 with the code discord_rate_limited. That response does not mean your key's own limit is used up: X-RateLimit-Remaining still shows what the key has left.

Every error body also includes requestId, and a 400 with the code bad_request identifies the invalid field in field. Match on code; message text can change.

The errors every request shares (401, 403, 405, 429, 500) are on the Errors page.