DualSoft

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.

Based on: AAS Part 2 API (IDTA-01002) v3.2 HTTP/REST Design Decisions, RFC 4648 §5Updated 2026-11-17

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

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 valuebase64url (no padding)
https://admin-shell.io/sampleSMaHR0cHM6Ly9hZG1pbi1zaGVsbC5pby9zYW1wbGVTTQ
https://admin-shell.io/idta/nameplate/3/0/NameplateaHR0cHM6Ly9hZG1pbi1zaGVsbC5pby9pZHRhL25hbWVwbGF0ZS8zLzAvTmFtZXBsYXRl
0112/2///61987#ABA565#009MDExMi8yLy8vNjE5ODcjQUJBNTY1IzAwOQ
https://example.com/aas/valve?v=1aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvdmFsdmU_dj0x
https://example.com/ids/aas/센서-01aHR0cHM6Ly9leGFtcGxlLmNvbS9pZHMvYWFzL-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.p1

JavaScript 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

Specifications and sources

← All guide topics