## 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.

```text
adyen 401 /payments API key missing checkout role
```

## Use 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
1. ('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