AES-GCM decrypt

POST /api/aes-gcm-decrypt2 quota units per call · cache hits free

Decrypt and authenticate an AES-GCM blob — given ciphertext + IV + tag, returns the plaintext or fails with a clear auth-tag error. Raw key or password (PBKDF2) supported.

Decrypts an AES-GCM blob produced by `aes-gcm-encrypt` (or any interoperable implementation). The auth tag is verified before the plaintext is returned — a mismatched ciphertext, key, IV, or AAD yields a 400 with a clear `authentication failed` error. Key modes mirror the encrypt tool: `raw` (supply key bytes) or `password` (supply password + salt + iterations to re-derive). **Output:** JSON with `plaintext` in the requested `outputFormat` (`text` for UTF-8, otherwise hex/base64).

Inputs

Name	Type	Default	Description
ciphertext*	string	—	Ciphertext (hex or base64).
ciphertextFormat	enum (hex \| base64)	"base64"	Encoding of `ciphertext`.
iv*	string	—	IV used during encryption (12 bytes).
ivFormat	enum (hex \| base64)	"base64"	Encoding of `iv`.
tag*	string	—	Auth tag from encryption.
tagFormat	enum (hex \| base64)	"base64"	Encoding of `tag`.
keyMode	enum (raw \| password)	"raw"	Whether `key` is raw bytes or a password to stretch.
key	string	—	Raw key (required when keyMode=raw).
keyFormat	enum (hex \| base64)	"hex"	Encoding of raw `key`.
password	string	—	Password (required when keyMode=password).
salt	string	—	PBKDF2 salt (required when keyMode=password).
saltFormat	enum (text \| hex \| base64)	"text"	Encoding of `salt`.
iterations	number (1000…10000000)	600000	PBKDF2 iterations.
keyBits	number (128…256)	256	Derived AES key length (keyMode=password).
aad	string	—	Additional authenticated data (must match what was used at encryption).
aadFormat	enum (text \| hex \| base64)	"text"	Encoding of `aad`.
outputFormat	enum (text \| hex \| base64)	"text"	How to render the plaintext.

Response

Modes: json. Cache: not cacheable.

Every response carries x-cache (HIT / MISS / BYPASS), x-cache-signature (stable across identical inputs), and the rate-limit headers listed below.

Quota & limits

Cost per call	2 units against the 10,000-unit monthly quota. Cache hits are free — only cache misses decrement.
Burst limit	200 requests per rolling minute, shared across all tools.
Max request size	`6 MiB` (base64 inflates file payloads ~33% — the limit applies to the decoded bytes).
Max response size	`6 MiB`
Timeout	30s wall clock.
Rate-limit headers	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Burst-Limit` on every response; `X-Quota-Warning` once 80% of the monthly quota is spent; `Retry-After` on 429s.

Errors

Errors are JSON with an error string; schema failures add a details object (Zod's flattened field errors).

Status	When	Body
400	Input fails the tool's schema (wrong type, missing required field, malformed base64) or the file bytes can't be parsed as the expected format.	{ "error": "invalid inputs", "details": { "fieldErrors": { … } } }
401	Missing or invalid X-Api-Key / X-Account-Id headers (or no session when called from the browser).	{ "error": "unauthorized" }
404	Unknown tool id, or calling /api/* on the website hostname instead of api.xtract.bot.	{ "error": "not found" }
413	Request body over the tool's max request size, or an image header declaring more megapixels than the tool's pixel budget.	{ "error": "…exceeds maxRequestBytes…" }
415	Content-Type isn't application/json on the json-body transport.	{ "error": "unsupported content-type; expected application/json" }
429	Monthly quota or the 200/min burst limit exhausted. Check Retry-After and the X-RateLimit-* headers.	{ "error": "monthly quota exceeded", "monthRemaining": 0, … }
5xx	Conversion engine failure. Safe to retry; if it persists, the input is hitting a bug — please report it.	{ "error": "…" }

Code samples

Built from the raw-key example.


curl -X POST https://api.xtract.bot/api/aes-gcm-decrypt \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Account-Id: $XTRACT_ACCOUNT_ID" \
  -H "X-Api-Key: $XTRACT_API_KEY" \
  -d '{
  "ciphertext": "knAZDSCqZdMHRe+ydFqsvx7IPHQ=",
  "iv": "oKGio6Slpqeoqaqr",
  "tag": "LiAR34CHfaYyz1OzxVgz7Q==",
  "key": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f"
}'