Current user¶

The current user is the account that presented the credential, represented as a user object. The routes here read that account, change it, and run its lifecycle operations.

Every route on this page except Get current user requires a user session (Authorization: Bearer <token>). A valid bot token or a valid OAuth2 access token is rejected with 403 ACCESS_DENIED.

Sudo verification¶

Security-sensitive changes (the username, lifecycle operations, forgetting authorised IPs, and several MFA routes) require proof of identity in the request body. The same three optional fields are accepted everywhere:

The first non-empty field in the order sudo_proof, mfa_code, password is checked.

A request without an accepted proof fails with 403:

{
  "error": "SUDO_REQUIRED",
  "code": "SUDO_MODE_REQUIRED",
  "message": "..."
}

A wrong password or code fails with 401 UNAUTHORIZED. Password attempts are limited to 10 per 5 minutes per account (bucket auth:sudo_pwd) and code attempts to 10 per 15 minutes (bucket auth:sudo_mfa).

Get current user¶

GET /users/@me

Returns the current user object. This is the one route on this page that also accepts a bot token (Authorization: Bot <token>); a bot receives its own user object with bot: true.

Also accepts an OAuth2 access token with the identify scope.

Access token response¶

With an OAuth2 access token the response is the same user object, with private fields replaced by neutral values:

Every other field is returned as it is for a session.

Response¶

Rate limit¶

40 requests per 10 seconds per user, bucket user:settings:get, shared with Get current user settings.

curl https://tebhos.com/api/v1/users/@me \
  -H "Authorization: Bearer $TEBHOS_TOKEN"

const res = await fetch("https://tebhos.com/api/v1/users/@me", {
  headers: { Authorization: `Bot ${process.env.TEBHOS_BOT_TOKEN}` },
});
const me = await res.json();
console.log(me.username, me.id);

import os, requests

r = requests.get(
    "https://tebhos.com/api/v1/users/@me",
    headers={"Authorization": f"Bot {os.environ['TEBHOS_BOT_TOKEN']}"},
)
print(r.json()["username"])

Modify current user¶

PATCH /users/@me

Modifies the current account and returns the resulting user object. Every field is optional; an omitted field is left unchanged. A body that changes nothing is not an error and returns the current user.

The body is processed in three steps, and an error in an earlier step stops the request: account fields are validated first, then a username change runs, then profile fields are written, and finally account fields are stored.

JSON body¶

Username (requires sudo verification)

Profile

Account

Limits¶

Saving the value a field already holds does not count against the per-field allowances.

Response¶

Side effects¶

The account's own sessions receive USER_UPDATE with the private user object at the top level. Guild members and friends receive the profile change as well, and the Gateway derives GUILD_MEMBER_UPDATE for guilds whose cached member data changed. See Gateway events.

curl -X PATCH https://tebhos.com/api/v1/users/@me \
  -H "Authorization: Bearer $TEBHOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"global_name": "Aria", "pronouns": "she/her", "mention_flags": 2}'

Change avatar¶

Avatars are uploaded directly to storage with a pre-signed URL, then confirmed.

Create avatar upload URL¶

POST /users/@me/avatar/upload-url

Returns:

Confirm avatar¶

POST /users/@me/avatar/confirm

TEBHOS strips image metadata (EXIF, GPS and similar), stores the file under its content hash, and returns {"avatar_hash", "image_url"}. An animated avatar (GIF, APNG or animated WebP, detected from the bytes) requires TEBHOS Pro and otherwise fails with 403. Avatar changes are limited to 25 per 30 minutes (400 INVALID_FORM_BODY, AVATAR_CHANGED_TOO_MANY_TIMES). A successful change emits USER_UPDATE.

To remove the avatar, send {"image_url": ""} to Modify current user.

See Uploads for the general upload flow.

Change banner¶

POST /users/@me/banner/upload-url and POST /users/@me/banner/confirm

Same bodies, limits and flow as Change avatar. The confirm route returns {"banner_hash", "banner_image_url"}. An animated banner requires TEBHOS Pro. Banner changes are limited to 25 per 30 minutes (BANNER_CHANGED_TOO_MANY_TIMES). The banner hash appears in the user object only while the account has premium.

Forget authorised IPs¶

DELETE /users/@me/authorized-ips

Deletes every authorised IP record of the account, so the next sign-in from any address needs fresh IP authorisation. Requires sudo verification; the body carries the proof fields.

Response¶

Rate limit¶

10 requests per 60 seconds per user, bucket user:authorized_ips:forget.

Disable current account¶

POST /auth/account/disable

Disables the account while keeping its data, and ends every session it owns, including the one that made the request. Signing in again re-activates the account. Requires sudo verification.

Response¶

Rate limit¶

5 requests per hour per user, bucket user:account:disable.

Schedule current account deletion¶

POST /auth/account/delete

Schedules the account for deletion 14 days from now and ends every session. Signing in before the deadline cancels the deletion. Requires sudo verification.

Response¶

Rate limit¶

5 requests per hour per user, bucket user:account:delete.

curl -X POST https://tebhos.com/api/v1/auth/account/delete \
  -H "Authorization: Bearer $TEBHOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mfa_code": "123456"}'

Accept current policies¶

POST /users/@me/terms-acceptance

Records acceptance of the current terms of service and privacy policy by setting terms_agreed_at and privacy_agreed_at to the request time. The body is ignored. Returns the updated user object and emits USER_UPDATE to the account's sessions. Repeating the call replaces both timestamps.

Rate limit¶

20 requests per 60 seconds per user, bucket user:update.

Legacy profile reads¶

The TEBHOS web client also uses two older, flat profile reads. New integrations should prefer Get current user.