Token exchange fails for form-urlencoded requests with a valid authorization code ("Invalid API key: should be in the format keystring:shared_secret"), identical JSON request succeeds

[jasper-0918]

Since at least July 31, 2026, POST https://api.etsy.com/v3/public/oauth/token returns HTTP 403 with:

{"error":"Invalid API key: should be in the format 'keystring:shared_secret'."}

for a spec-compliant authorization_code + PKCE token exchange sent as Content-Type: application/x-www-form-urlencoded, when the request carries a valid, freshly issued authorization code. The identical request sent as Content-Type: application/json succeeds and returns tokens.

RFC 6749 §4.1.3 requires token requests to be form-urlencoded, so this breaks standards-compliant OAuth client libraries (hit this in n8n, whose generic OAuth2 client cannot switch to JSON bodies, and most OAuth2 SDKs are in the same position).

Reproduction (personal app, PKCE, single valid code each attempt):

1. Complete https://www.etsy.com/oauth/connect normally (consent succeeds, code is issued to the registered redirect URI).
2. Exchange the code:

Fails (403, error above):

POST /v3/public/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=<keystring>&redirect_uri=<uri>&code=<code>&code_verifier=<verifier>

Succeeds (200, tokens issued), same fields:

POST /v3/public/oauth/token
Content-Type: application/json

{"grant_type":"authorization_code","client_id":"<keystring>","redirect_uri":"<uri>","code":"<code>","code_verifier":"<verifier>"}

Additional matrix (all form-urlencoded unless noted):

Request shape	Result
Form body, keystring client_id, fake code	invalid_grant / code is invalid (key check passes with a fake code, so the failure only appears with real codes, which makes this hard to debug)
Form body, keystring client_id, real code	403 Invalid API key: should be in the format 'keystring:shared_secret'
Form body + x-api-key: keystring:secret header, real code	invalid_client / client_id is invalid
client_id=keystring:secret (compound)	invalid_client / client_id is invalid
HTTP Basic auth (keystring:secret)	Invalid access token: not a Bearer token or token format is incorrect
JSON body, keystring client_id, real code	200, tokens issued

Sample failing request trace: x-etsy-request-uuid: Euwds5TllZ3QOzHHmZTnSwprtQa7 (2026-07-31 01:45:29 UTC, served by cache-bos-kbos510041-BOS).

This looks related to the February 2026 shared-secret enforcement: the form-urlencoded path appears to route token requests through the OpenAPI key validation (which now demands the compound x-api-key format) instead of the OAuth token handler, while the JSON path routes correctly.

Could you confirm whether form-urlencoded token requests are still supported, and restore RFC-compliant handling? Happy to provide more traces.

[openapi-support[bot]]

We tested this against api.etsy.com today (2026-07-31) with both body formats, and both succeeded with a 200 and valid tokens.

Form-urlencoded (RFC 6749 §4.1.3 compliant):

POST /v3/public/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=<keystring>&redirect_uri=<uri>&code=<code>&code_verifier=<verifier>

JSON body:

POST /v3/public/oauth/token
Content-Type: application/json

{"grant_type":"authorization_code","client_id":"<keystring>","redirect_uri":"<uri>","code":"<code>","code_verifier":"<verifier>"}

In both cases client_id is the bare keystring — not the compound keystring:shared_secret format.

Your RFC 6749 §4.1.3 read is correct: form-urlencoded is the required encoding and JSON is not in the spec for token requests. We also searched across our logs and are not seeing any broader elevation in 403s on the token endpoint, which further suggests this isn't a universal server regression. The fact that both formats succeeded in our verification but form-urlencoded fails for yours points to something app-specific.

[jasper-0918]

Thanks for testing it on your side. Since you suspect this is app-specific, the original report includes a request trace uuid from a real failing form-encoded exchange: Euwds5TllZ3QOzHHmZTnSwprtQa7. That request returned the 403 "Invalid API key" error with a bare keystring as client_id, the same request shape that succeeds when sent as JSON.

If you need anything else from our side to look into the app's state, let us know. The JSON workaround is holding up in the meantime, but we'd rather be back on the standard flow.