> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Adyen

*This is for the Adyen Multi-Auth and Adyen connector. It authenticates with the same single Adyen Management API key as the standard Adyen connector, but it is wired on the Lumos credentials framework, validates that the key carries the required role, and enables provisioning write actions.*

## After this article

You will be able to connect Adyen to Lumos to sync your Adyen Customer Area users, their roles, and groups, and to provision users (create, update, activate, deactivate) and assign or unassign entitlements.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| :- | :- | :- | :- | :- |
| Users | Account | Yes | Yes | Customer Area user accounts. Provisioning covers create, update, activate, and deactivate |
| Roles | Permission | Yes | Yes | Roles in Adyen (assign and unassign entitlement) |
| Groups | Permission | Yes | Yes | Groups in Adyen (assign and unassign entitlement) |

On connect, `validate_token_credential` runs an active probe (`GET /v3/me`) and reads the `roles` array. A `401` means the key is invalid or revoked. A missing required role fails validation and tells you to enable it under **Developers → API credentials → Permissions**.

## Required plan and roles

* **Adyen roles:** to generate the API key you need the **Merchant admin** role and the **Manage API credentials** role.
* **API credential role:** the credential Lumos uses must have **Management API - Users read and write** enabled (API version v3). The connector validates this role on connect and fails if it is missing. If you cannot find this role, contact Adyen support to assign it to your API credential. Click the question mark in the top-right corner of the UI, select **Ticket Manager**, and click the **Contact Support** button. For type of issue select **Integrations**, and for integration type select **Web**.
* **Credential model:** the connector offers a single token credential, so you still supply one Adyen Management API key. It is sent as the `X-API-Key` header. The difference from the standard variant is the credentials framework, the role validation, and the enabled write path.
* **Permission scoping:** read plus write. The **Users read and write** role covers both the sync of users, groups, and roles and the provisioning actions.

## Read-only access vs provisioning

**Is read-only possible?** No. The connection authenticates with a single Adyen Management API key, and the role that key must carry, Management API - Users read and write, grants read and write together. Adyen does not offer a narrower read-only role, and the connector actively validates the required role on connect and fails if it is missing.

**What full provisioning requires.** An Adyen Management API key generated by a user with the Merchant admin and Manage API credentials roles, with Management API - Users read and write enabled under Permissions, plus your Company Name and Environment (Live or Test). Follow the steps below. Provisioning covers creating, updating, activating, and deactivating users, and assigning or unassigning role and group entitlements.

**Watch out for.** Validation happens on connect (a `GET /v3/me` call that checks the roles array), so a missing or revoked role fails the connection immediately rather than failing quietly later. Live and Test API keys only work against their matching environment (`management-live.adyen.com` or `management-test.adyen.com`), and picking the wrong one is a common connection failure.

## Instructions

**Phase 1: Generate an API key in Adyen**

1. Log in to your Adyen **Customer Area**.
2. Go to **Developers → API credentials** and select the API credential username for your integration (for example `ws@Company.[YourCompanyAccount]`).
3. Under **Server settings → Authentication**, select the **API key** tab.
4. Click **Generate API key** and copy the key.
5. Under **Permissions → Roles**, make sure **Management API - Users read and write** is selected, then click **Save Changes**.
6. Note your **Company Name**: open the dropdown menu in the top-left corner of the Customer Area and copy the company account name.

**Phase 2: Connect in Lumos**

1. Click the Adyen (multi-auth) card in your Lumos integrations (reconnect an existing card or add a new one).
2. Enter the **API Key** and **Company Name**.
3. Select the **Environment**: **Live** (`management-live.adyen.com`) or **Test** (`management-test.adyen.com`).
4. Click **Connect**.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**Connection fails with a valid API key.** Check that the **Environment** matches where the key was generated. Live keys only work against `management-live.adyen.com`, Test keys against `management-test.adyen.com`. Also confirm the **Company Name** exactly matches the company account name from the Customer Area dropdown.

**Connect fails with "API key is invalid or has been revoked".** The active probe against `GET /v3/me` returned a `401`. Regenerate the key on the correct API credential and reconnect.

**Users fail to sync or return permission errors.** Verify the API credential has **Management API - Users read and write** under **Permissions → Roles** and that you clicked **Save Changes**. If the role is not listed at all, ask Adyen support to enable it for your credential.

**Wrong credential selected.** Make sure you generated the key on the API credential intended for Lumos (the `ws@Company.[YourCompanyAccount]` username), not another integration's credential.