Base64URL Converter and Encoding Rules for AAS API Identifiers
The AAS REST API does not put identifiers of AAS, Submodels or ConceptDescriptions into URLs as-is; it base64url-encodes them first. The rules are short, but a wrong alphabet or a stray padding character can be enough for the server not to find the id. This page follows Part 2 v3.2 and RFC 4648.
Base64url converter
Paste a whole URL such as /shells/aHR0…/submodels/aHR0… and press Decode to decode every identifier in it.
- base64url (no padding · AAS API rule)
- base64url (with padding)
- Decoded
- Identifiers found in the URL
Runs only in your browser; nothing you type is sent anywhere.
Why base64url
AAS identifiers are usually IRIs, URNs or IRDIs, for example https://admin-shell.io/idta/nameplate/3/0/Nameplate or 0112/2///61987#ABA565#009. Placed in a path unchanged, / would split path segments, # would start a fragment and ? would start the query.
Part 2 therefore requires identifiers of Identifiables (AAS, Submodel, ConceptDescription) to be base64url-encoded when passed to the API. The packageId of the AASX File Server, the handleId of asynchronous operations and the query parameters semanticId and assetIds are also passed as base64url.
The rules (Part 2 v3.2)
- The alphabet is the URL-safe alphabet of RFC 4648 §5: - instead of + and _ instead of /.
- No padding. Part 2 states that base64url values must not contain or end with = (made explicit in v3.1).
- The input is the UTF-8 byte array of the string.
- For the semanticId query, the Reference is serialized to JSON and then base64url-encoded; assetIds works the same way with SpecificAssetId objects. An encoded semanticId may be at most 3072 characters (Constraint AASa-002).
- idShortPaths are not base64url-encoded; they are URL-encoded.
- The result contains only A-Z, a-z, 0-9, - and _. All of these are unreserved characters in RFC 3986, so no further percent-encoding is needed.
Step-by-step example
Take https://example.com/ids/aas/센서-01 (the Korean word means sensor). (1) Convert it to UTF-8: the two Korean characters take 6 bytes, 37 bytes in total. (2) Standard base64 gives aHR0cHM6Ly9leGFtcGxlLmNvbS9pZHMvYWFzL+yEvOyEnC0wMQ==. (3) Replace + with - and / with _. (4) Remove the trailing ==. The result is aHR0cHM6Ly9leGFtcGxlLmNvbS9pZHMvYWFzL-yEvOyEnC0wMQ and the request becomes GET /shells/aHR0cHM6Ly9leGFtcGxlLmNvbS9pZHMvYWFzL-yEvOyEnC0wMQ.
The table shows Python base64.urlsafe_b64encode output with = removed. The first row matches the example in the Part 2 text. In the fourth row, standard base64 would put / where base64url has _.
semanticId query example: the Reference {"type":"ExternalReference","keys":[{"type":"GlobalReference","value":"https://admin-shell.io/idta/nameplate/3/0/Nameplate"}]}, serialized without whitespace, gives GET /submodels?semanticId=eyJ0eXBlIjoiRXh0ZXJuYWxSZWZlcmVuY2UiLCJrZXlzIjpbeyJ0eXBlIjoiR2xvYmFsUmVmZXJlbmNlIiwidmFsdWUiOiJodHRwczovL2FkbWluLXNoZWxsLmlvL2lkdGEvbmFtZXBsYXRlLzMvMC9OYW1lcGxhdGUifV19. Part 2 notes that whitespace differences in the JSON lead to different encoded strings and that servers must operate on the original content.
| Original value | base64url (no padding) |
|---|---|
| https://admin-shell.io/sampleSM | aHR0cHM6Ly9hZG1pbi1zaGVsbC5pby9zYW1wbGVTTQ |
| https://admin-shell.io/idta/nameplate/3/0/Nameplate | aHR0cHM6Ly9hZG1pbi1zaGVsbC5pby9pZHRhL25hbWVwbGF0ZS8zLzAvTmFtZXBsYXRl |
| 0112/2///61987#ABA565#009 | MDExMi8yLy8vNjE5ODcjQUJBNTY1IzAwOQ |
| https://example.com/aas/valve?v=1 | aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvdmFsdmU_dj0x |
| https://example.com/ids/aas/센서-01 | aHR0cHM6Ly9leGFtcGxlLmNvbS9pZHMvYWFzL-yEvOyEnC0wMQ |
Decoding
To decode, reverse the steps: replace - with + and _ with /, append = until the length is a multiple of 4, decode as standard base64, and read the bytes as UTF-8.
If the length modulo 4 is 2, append ==; if it is 3, append =. A remainder of 1 is never valid base64url. Python's base64.urlsafe_b64decode raises Incorrect padding when the padding is missing, so restore it first.
Common mistakes
- Using standard base64: a / in the value splits the path, and a + may be read as a space in query strings.
- Keeping the = padding: this violates the spec. Check whether your library pads by default.
- Double encoding: percent-encoding the id first (https%3A%2F%2F...) and then applying base64url produces a completely different string. Percent-encoding the base64url result is also unnecessary.
- Not using UTF-8: building bytes with another encoding such as CP949 changes the result for non-ASCII ids. Browser btoa cannot take non-Latin-1 strings directly, so create UTF-8 bytes with TextEncoder first.
- base64url-encoding an idShortPath: idShortPaths are URL-encoded, e.g. sme1.sme2[0].p1 becomes sme1.sme2%5B0%5D.p1.
- Changing letter case: base64url is case-sensitive. Proxies or code that lower-case URLs corrupt the value.
Python example
Standard library only. The decode function accepts input with or without padding.
import base64
def encode_id(identifier: str) -> str:
"""AAS identifier -> base64url without padding (IDTA-01002)."""
raw = base64.urlsafe_b64encode(identifier.encode("utf-8"))
return raw.decode("ascii").rstrip("=")
def decode_id(encoded: str) -> str:
"""base64url (with or without padding) -> identifier."""
padded = encoded + "=" * (-len(encoded) % 4)
return base64.urlsafe_b64decode(padded).decode("utf-8")
sm_id = "https://example.com/ids/aas/센서-01"
enc = encode_id(sm_id)
print(enc) # aHR0cHM6Ly9leGFtcGxlLmNvbS9pZHMvYWFzL-yEvOyEnC0wMQ
assert decode_id(enc) == sm_id
# idShortPath is URL-encoded, not base64url
from urllib.parse import quote
print(quote("sme1.sme2[0].p1", safe="")) # sme1.sme2%5B0%5D.p1JavaScript example
Works in browsers and Node.js. In Node.js, the Buffer base64url encoding gives the same unpadded result.
// Works in browsers and Node.js (TextEncoder, btoa, atob)
function encodeId(id) {
const bytes = new TextEncoder().encode(id); // UTF-8
let bin = "";
for (const b of bytes) bin += String.fromCharCode(b);
return btoa(bin)
.replace(/\+/g, "-").replace(/\//g, "_") // RFC 4648 section 5
.replace(/=+$/, ""); // no padding
}
function decodeId(s) {
let b64 = s.replace(/-/g, "+").replace(/_/g, "/");
b64 += "=".repeat((4 - (b64.length % 4)) % 4);
const bytes = Uint8Array.from(atob(b64), c => c.charCodeAt(0));
return new TextDecoder().decode(bytes);
}
encodeId("https://admin-shell.io/sampleSM");
// "aHR0cHM6Ly9hZG1pbi1zaGVsbC5pby9zYW1wbGVTTQ"
// Node.js only: Buffer.from(id, "utf8").toString("base64url") gives the same result.FAQ
What is a string that starts with aHR0cHM6Ly…?
It is an identifier starting with https:// encoded as base64url (or base64). https:// always becomes aHR0cHM6Ly and http:// becomes aHR0cDovL. Paste it into the converter on this page and press Decode to get the original id.
What is the difference between base64url and base64?
Per RFC 4648, only characters 62 and 63 differ: base64 uses + and /, base64url uses - and _. On top of that, the AAS API requires the = padding to be removed.
The server returns 404 although the id is correct. What should I check?
Check whether the encoded value contains +, / or =, whether whitespace or a line break slipped into the id, and whether you encoded UTF-8. Then decode the value and compare it with the original id character by character.
When searching Submodels by semanticId, do I encode only the IRI string?
Part 2 says the semanticId query takes the whole Reference serialized to JSON and then base64url-encoded. Unlike ids in the path, you encode a Reference object, not a single string.
Related articles
- AAS HTTP/REST API v3 in Practice (IDTA-01002, Part 2)AAS Part 2 HTTP/REST API v3.2: service profiles, /shells and /submodels paths, $value suffixes, level, extent, base64url IDs, idShortPath and paging.
- AAS identifiers: getting id and idShort rightAAS v3 identifiers explained: Identifier strings up to 2048 characters, idShort patterns, IRI vs IRDI vs Custom, the removed idType, and good IRI patterns.
- semanticId: giving AAS data a machine-readable meaningHow semanticId and supplementalSemanticIds work in AAS v3.2, where ConceptDescription and IEC 61360 fit, and how to pick ECLASS or IEC CDD IDs (with JSON).
- globalAssetId and specificAssetIds: designing and finding asset IDsRules for globalAssetId and specificAssetIds in AAS v3 AssetInformation (AASd-131, 116, 133), changes from v2, ID design, Discovery lookups and common mistakes.
Specifications and sources
- IDTA-01002-3-2 Part 2 API, HTTP/REST API: Design Decisions (base64url, padding, UTF-8, semanticId and assetIds encoding)
- IDTA-01002-3-2 Part 2 API, HTTP/REST API: Addressing Resources (base64url example, URL-encoded idShortPath)
- IDTA-01002-3-2 Part 2 API, Change Log V3.0.4 to V3.1: padding not allowed for base64url (#423)
- admin-shell-io/aas-specs-api issue #423 (padding)
- admin-shell-io/aas-specs-api, Part2-API-Schemas/openapi.yaml: SubmodelIdentifier, SemanticId (maxLength 3072), AssetIds, HandleId
- RFC 4648 §5 Base 64 Encoding with URL and Filename Safe Alphabet; §3.2 Padding
- RFC 3986 §2.3 Unreserved Characters
- IDTA submodel-templates, Digital Nameplate 3.0.3 (semanticId https://admin-shell.io/idta/nameplate/3/0/Nameplate, ManufacturerName 0112/2///61987#ABA565#009)
