adyen 401 on /payments: API key missing the checkout role
Explains Adyen 401 responses on the /payments endpoint: the API key lacks the checkout role. Use when /payments returns 401 while other endpoints work. Not for invalid-key or expired-key errors.
TL;DR
The API key is valid but not authorized for checkout operations. In the Adyen Customer Area, add the checkout role (API checkout) to the key, wait for propagation, and retry. A 401 with a correct key is always a roles problem.
adyen 401 /payments API key missing checkout roleUse this when
- POST /payments returns 401 but the key works elsewhere.
- A new API key was created and checkout immediately fails.
- You need to audit which roles each key holds.
Not for this skill when
- Every endpoint returns 401. The key itself is wrong or revoked.
- The error is 403. That is a different authorization layer.
Steps
- ('Confirm the key is correct: test it against a harmless endpoint. Verify: the key authenticates.', 'In the Customer Area, open the API credential and check its roles. Verify: the checkout role is absent.', 'Add the checkout role to the credential and save. Verify: the role list includes it.', 'Wait a few minutes for role propagation, then retry /payments. Verify: the endpoint returns a payment result, not 401.', 'Document the required roles per key in your runbook. Verify: future keys are created with roles attached.')
Variant phrasings
adyen 401 unauthorized payments api
Symptom search.
adyen api key roles checkout
Config search.
adyen payments 401 new api key
New-key search.
Compatibility: Adyen Checkout API, Customer Area API credentials.
Why it happens
Adyen API keys are role-scoped: a key only works on the endpoints its roles allow. Checkout operations need the checkout role explicitly. New keys are often created with default or copied roles that omit checkout, so the key authenticates fine (no invalid-key error) but /payments refuses it with 401. The 401 names authentication, but the real problem is authorization.
Edge cases / pitfalls
- Role changes take a few minutes to propagate. Retrying instantly still 401s.
- Test and live credentials have separate role sets. Fixing test does not fix live.
- Least privilege is good, but a key missing its one required role is just broken.
- Rotate keys with a role checklist, not by copying the old key and hoping.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_MgWKswBT3eZtOhhObR6VCg