Bitmask flags decoder
With read (1), write (2), execute (4) and admin (8), the value 13 decodes to read, execute and admin, with nothing left unexplained. Enter a stored number and your own list of named bits to see which permissions or options are on. Free in your browser.
- Free
- Runs in your browser
- No sign-up
- Your data stays on your device
Run — free
Worked example
- Value
- 13
- Active flags
- read, execute, admin
- Unknown bits
- 0
The bitmask flags decoder turns a compact integer into the permission, feature, status, or option names it represents. Provide the stored value and a list that maps each name to a power-of-two bit. The result preserves your declaration order, returns every active name, and reports any value left over from bits you did not define.
How a single number stores several options
A bitmask packs many yes-or-no settings into one integer. Each option owns one binary position worth a power of two: 1, 2, 4, 8, 16 and so on. Because those positions never overlap, adding the values of the options that are on gives a unique total, and that total can be taken apart again. The decoder checks every name in your list to see whether its position is present in the stored value. 13, for instance, is 8 plus 4 plus 1, so with read as 1, execute as 4 and admin as 8 those three come back as active, in the order you declared them. A value of zero is valid and simply means no option is on.
What the leftover tells you, and common slips
Whatever part of the number your list does not explain is reported separately instead of being dropped. A leftover of zero means your definitions cover the whole value; anything else often points to a flag added on the server, an internal option you left out on purpose or lists from two different versions. Typical mistakes are giving a flag a value that is not a power of two, such as 3, or reusing the same bit for two names; both are refused with a clear message instead of producing a plausible but wrong list. Names are trimmed and must be unique.
Describe the mask with explicit named bits
Start with the non-negative integer in the value field, then add one flags row for every meaning your system defines. Each row contains a name and a bit. The bit must be a positive power of two: 1, 2, 4, 8, 16, and so on.
Those values represent independent binary positions, which makes them safe to combine by addition or bitwise OR. Names are trimmed and must remain unique, and bit values must also be unique, because two labels for the same position would make the decoded answer ambiguous. Inputs use JavaScript-safe non-negative integers, supporting exact values through 9,007,199,254,740,991 and individual declared bits through 4,503,599,627,370,496.
Invalid records fail clearly instead of being silently coerced into a plausible but incorrect permission list.
What you can do with it
Explain access-control fields
Turn a stored permission mask into readable names before showing it in an admin interface or audit export.
Migrate legacy configuration
Expand compact numeric settings into explicit booleans or labels during a database or application migration.
FAQ
What values can I decode?
Any non-negative JavaScript-safe integer. Each declared flag bit must be a unique positive power of two.
Can flag names contain spaces?
Yes. Names are strings and surrounding whitespace is trimmed. Empty names and duplicate trimmed names are rejected.
Why must each flag be a power of two?
Because each power of two, 1, 2, 4, 8, 16 and so on, is its own binary position, so flags can be added together without overlapping. For the same reason every bit and every name must be unique, or the decoded answer would be ambiguous.
What does a leftover value mean?
It is the part of the number your list does not explain. Decoding 13 with only read (1), write (2) and execute (4) leaves 8 over. That often signals a new flag, an internal option you left out on purpose or a version mismatch.
Does the order of my flag list matter?
Only for display. Definitions can go in any order, and the active names come back in the order you declared them, so your interface keeps its preferred order instead of a numeric sort.
Related tools
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/dev/bitmask-flags-decode \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"value":13,"flags":[{"name":"read","bit":1},{"name":"write","bit":2},{"name":"execute","bit":4},{"name":"admin","bit":8}]}'const res = await fetch("https://api.kit.forhosting.com/dev/bitmask-flags-decode", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"value": 13,
"flags": [
{
"name": "read",
"bit": 1
},
{
"name": "write",
"bit": 2
},
{
"name": "execute",
"bit": 4
},
{
"name": "admin",
"bit": 8
}
]
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/dev/bitmask-flags-decode",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"value": 13,
"flags": [
{
"name": "read",
"bit": 1
},
{
"name": "write",
"bit": 2
},
{
"name": "execute",
"bit": 4
},
{
"name": "admin",
"bit": 8
}
]
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev/bitmask-flags-decode", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"value":13,"flags":[{"name":"read","bit":1},{"name":"write","bit":2},{"name":"execute","bit":4},{"name":"admin","bit":8}]}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"value":13,"flags":[{"name":"read","bit":1},{"name":"write","bit":2},{"name":"execute","bit":4},{"name":"admin","bit":8}]}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev/bitmask-flags-decode", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"value": 13,
"flags": [
{
"name": "read",
"bit": 1
},
{
"name": "write",
"bit": 2
},
{
"name": "execute",
"bit": 4
},
{
"name": "admin",
"bit": 8
}
]
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "dev.bitmask_flags_decode",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Limits
max_flags | 256 |
max_safe_integer | 9007199254740991 |
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |
Technical notes
It is useful when reading database fields, API payloads, protocol values, access-control settings, and legacy configuration without manually converting numbers to binary or relying on language-specific bitwise behavior.
Describe the mask with explicit named bits
Definitions may appear in any order; active_flags follows the order you supplied, which lets an application keep a preferred display order instead of receiving an arbitrary numeric sort. The decoder accepts zero as a valid mask and returns an empty active_flags array for it.
Understand active flags and unknown bits
For every declaration, the decoder tests whether that binary position is present in value. Keeping that remainder visible is safer than dropping information. The original value is returned unchanged so logs and downstream checks can retain exact provenance. If it is present, the corresponding name is appended to active_flags and its numeric bit contributes to the declared active total. The response also includes unknown_bits, calculated as the original value minus all active bits that were declared. A zero unknown_bits value means the supplied definitions fully explain the mask. A nonzero value is not automatically an error: it often signals a newly introduced server flag, an intentionally omitted internal option, or a schema version mismatch. For example, if value is 13 and the declared bits are read=1, write=2, execute=4, and admin=8, the active names are read, execute, and admin, while unknown_bits is zero. If bit 8 were omitted from the definitions, the same input would return read and execute with unknown_bits equal to 8.
Use deterministic decoding in permission and option workflows
Bitmasks are common in database columns, operating-system modes, feature switches, device registers, game state, and third-party API responses because many booleans fit into one integer. This capability makes those fields readable at an integration boundary. Store the flag definitions beside the schema version, call the decoder when a record enters your pipeline, and use active_flags for display, filtering, or policy checks. Monitor unknown_bits as a compatibility signal: a nonzero remainder can route the record for review before software mistakes a new permission for an ordinary old value. The algorithm performs bounded arithmetic over at most 256 definitions and uses no network, clock, locale, random source, or mutable state, so identical JSON always produces identical JSON. It also avoids JavaScript's signed 32-bit bitwise operators and therefore handles exact masks well above 32 bits within the safe-integer range. Interactive decoding is free, while successful automated API tasks use the published base price of $0.002.
Integration use cases
Inspect API and protocol options
Decode combined option values from an integration while retaining undeclared bits as a schema-drift warning.
Technical questions
What does unknown_bits mean?
It is the portion of value that is set but not represented by any supplied flag definition. Zero means the declarations explain the entire mask.
Does the result preserve flag order?
Yes. active_flags follows the order of the supplied definitions, regardless of their numeric bit order.
How much does the API cost?
Each successful API task uses the published base price of $0.002. You can also run the decoder free in the browser.