Adyen User Management API Guide

Auth method: API Key (X-API-Key header)

Setup steps

1. Log in to the Adyen Customer Area.
2. Go to Developers > API credentials and select or create a web service credential (e.g., ws@Company.[YourCompanyAccount]).
3. Under Server settings > Authentication, select the API key tab and click Generate API key.
4. Copy and securely store the API key - it cannot be retrieved again after leaving the page.
5. Assign the required roles (e.g., 'Management API-Users read and write') under Roles and Associated Accounts.
6. Set the API key as the X-API-Key header value in all requests.
7. For live access, generate a separate API key in your live Customer Area and use https://management-live.adyen.com/v3.

Required scopes

List company-level users

• Method: GET
• URL: https://management-live.adyen.com/v3/companies/{companyId}/users
• Watch out for: Requires 'Management API-Users read and write' role. Supports partial username filter via ?username= query param.

Request example

GET /v3/companies/YOUR_COMPANY_ID/users?pageSize=10&pageNumber=1
X-API-Key: YOUR_API_KEY

Response example

{
  "data": [{"id":"user123","email":"user@example.com","active":true}],
  "itemsTotal": 42,
  "pagesTotal": 5
}

Create company-level user

• Method: POST
• URL: https://management-live.adyen.com/v3/companies/{companyId}/users
• Watch out for: SSO loginMethod requires SSO to be pre-configured in Adyen before user creation. username must match email when loginMethod is Email.

Request example

POST /v3/companies/YOUR_COMPANY_ID/users
X-API-Key: YOUR_API_KEY
{
  "email": "user@example.com",
  "name": {"firstName": "Jane", "lastName": "Doe"},
  "username": "user@example.com",
  "loginMethod": "Email"
}

Response example

{
  "id": "user123",
  "email": "user@example.com",
  "active": true,
  "name": {"firstName": "Jane", "lastName": "Doe"}
}

Get company-level user details

• Method: GET
• URL: https://management-live.adyen.com/v3/companies/{companyId}/users/{userId}
• Watch out for: Requires 'Management API-Users read and write' role.

Request example

GET /v3/companies/YOUR_COMPANY_ID/users/user123
X-API-Key: YOUR_API_KEY

Response example

{
  "id": "user123",
  "email": "user@example.com",
  "active": true,
  "roles": ["Merchant Standard Role"]
}

Update company-level user details

• Method: PATCH
• URL: https://management-live.adyen.com/v3/companies/{companyId}/users/{userId}
• Watch out for: PATCH is partial update. Only send fields to change. No DELETE endpoint for users - deactivate by setting active=false.

Request example

PATCH /v3/companies/YOUR_COMPANY_ID/users/user123
X-API-Key: YOUR_API_KEY
{
  "active": false,
  "roles": ["Merchant Standard Role"]
}

Response example

{
  "id": "user123",
  "email": "user@example.com",
  "active": false
}

List merchant-level users

• Method: GET
• URL: https://management-live.adyen.com/v3/merchants/{merchantId}/users
• Watch out for: Merchant-level users are scoped to a specific merchant account, distinct from company-level users.

Request example

GET /v3/merchants/YOUR_MERCHANT_ID/users?pageSize=10
X-API-Key: YOUR_API_KEY

Response example

{
  "data": [{"id":"user456","email":"merchant@example.com"}],
  "itemsTotal": 5
}

Create merchant-level user

• Method: POST
• URL: https://management-live.adyen.com/v3/merchants/{merchantId}/users
• Watch out for: Requires 'Management API-Users read and write' role at merchant level.

Request example

POST /v3/merchants/YOUR_MERCHANT_ID/users
X-API-Key: YOUR_API_KEY
{
  "email": "merchant@example.com",
  "name": {"firstName": "John", "lastName": "Smith"},
  "username": "merchant@example.com"
}

Response example

{
  "id": "user456",
  "email": "merchant@example.com",
  "active": true
}

Update merchant-level user

• Method: PATCH
• URL: https://management-live.adyen.com/v3/merchants/{merchantId}/users/{userId}
• Watch out for: loginMethod SSO requires pre-existing SSO configuration. Possible loginMethod values: 'Username & account', 'Email', 'SSO'.

Request example

PATCH /v3/merchants/YOUR_MERCHANT_ID/users/user456
X-API-Key: YOUR_API_KEY
{
  "active": true,
  "roles": ["Merchant Standard Role"]
}

Response example

{
  "id": "user456",
  "active": true,
  "roles": ["Merchant Standard Role"]
}

Create API credential (web service user)

• Method: POST
• URL: https://management-live.adyen.com/v3/companies/{companyId}/apiCredentials
• Watch out for: The API key in the response is shown only once. Store it immediately. Old API key remains valid 24 hours after rotation.

Request example

POST /v3/companies/YOUR_COMPANY_ID/apiCredentials
X-API-Key: YOUR_API_KEY
{
  "roles": ["Management API-Users read and write"],
  "description": "Automation credential"
}

Response example

{
  "id": "cred123",
  "username": "ws@Company.YourCompany",
  "apiKey": "AQE...",
  "active": true
}

• Rate limits: The Management API documentation states that live environment endpoints are subject to rate limits, but does not publish specific numeric thresholds for the /users endpoints in the Management API docs. The Legal Entity Management API (a separate API) documents 700 req/5s live and 200 req/5s test as a reference point. When rate-limited, the API returns an error with detail 'too many requests'.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: No rate-limit response headers are documented for the Management API. Adyen recommends exponential backoff on retries. A 'too many requests' error in the detail field signals rate limiting. The old API key remains valid for 24 hours after a new one is generated.
• Pagination method: offset
• Default page size: 10
• Max page size: 100
• Pagination pointer: pageNumber / pageSize

• Webhooks available: Yes
• Webhook notes: Adyen uses webhooks to inform your system about events that happen with your Adyen company and merchant accounts, stores, payment terminals, and payment methods when using the Management API. Webhooks are configured via POST /companies/{companyId}/webhooks or /merchants/{merchantId}/webhooks.
• Alternative event strategy: Poll GET /companies/{companyId}/users or GET /merchants/{merchantId}/users for user state changes, as no dedicated user-change webhook event is documented.
• Webhook events: merchant.created, merchant.updated, paymentMethod.created, paymentMethod.updated, paymentMethod.requestScheduledForProcessing, terminal.assigned, terminal.unassigned

• SCIM available: No

• SCIM version: Not documented

• Plan required: Enterprise

• Endpoint: Not documented

• Supported operations: Group Linking, Schema Discovery, Create Users, Update Attributes

Limitations:

• No native SCIM endpoint documented by Adyen; SCIM provisioning is handled via IdP (Okta, Entra ID) integration at the Enterprise tier.
• Requires company account (not merchant account).
• Requires Merchant admin or Merchant user management role.
• SSO must be configured before enabling SCIM-based provisioning.
• Keep at least one admin without SSO for emergency access.
• Legal notice acceptance required for SSO setup.

Three scenarios cover the primary automation use cases. Provisioning an SSO-enabled user: SSO must be fully configured in Adyen before the API call - if it is not, the request will be rejected.

POST to /v3/companies/{companyId}/users with loginMethod='SSO', email, name, username (matching email), and the target roles array. store the returned id immediately for subsequent operations.

Offboarding: retrieve the user id via GET /v3/companies/{companyId}/users?

username=, then PATCH with {"active": false}; confirm the state change with a follow-up GET; note that API credentials associated with the user must be deactivated separately under /v3/companies/{companyId}/apiCredentials - user deactivation does not cascade.

API credential rotation: POST to /v3/companies/{companyId}/apiCredentials/{apiCredentialId}/generateApiKey, copy the key from the response immediately (it is shown only once), and propagate it to all dependent systems within 24 hours - the old key is hard-invalidated at that boundary with no extension.

Provision a new SSO-enabled company user

1. Ensure SSO is configured in Adyen Customer Area before proceeding.
2. POST /v3/companies/{companyId}/users with email, name, username (matching email), loginMethod='SSO', and desired roles.
3. Store the returned user id for future PATCH/GET operations.
4. Verify user is active via GET /v3/companies/{companyId}/users/{userId}.

Watch out for: If SSO is not pre-configured, the API will reject loginMethod='SSO'. Fall back to 'Email' or 'Username & account' until SSO is ready.

Deactivate a user (offboarding)

1. Retrieve the user's id via GET /v3/companies/{companyId}/users?username=user@example.com.
2. PATCH /v3/companies/{companyId}/users/{userId} with body {"active": false}.
3. Confirm deactivation via GET /v3/companies/{companyId}/users/{userId} and verify active=false.

Watch out for: There is no DELETE endpoint. Users can only be deactivated, not permanently deleted via API.

Rotate API credentials for a web service user

1. POST /v3/companies/{companyId}/apiCredentials/{apiCredentialId}/generateApiKey to generate a new API key.
2. Immediately copy and store the new API key from the response - it is shown only once.
3. Update all systems using the old key within 24 hours (old key expires after 24 hours).
4. Optionally PATCH /v3/companies/{companyId}/apiCredentials/{apiCredentialId} to update roles or allowed origins.

Watch out for: The old API key stops working exactly 24 hours after a new one is generated. There is no overlap extension.

The Management API is well-structured but carries several non-obvious constraints that will surface in production. Role delegation is bounded: only roles assigned to the ws@Company. credential can be delegated to other API credentials, so a credential missing a required role cannot self-escalate - a human admin must intervene.

The company/merchant scope split means a single sync job is insufficient; teams must enumerate both /companies/{companyId}/users and /merchants/{merchantId}/users to get a complete user picture. No user-change webhook events are documented, so detecting state changes requires polling both endpoints. The Management API is versioned in the URL path (/v3/); breaking changes will require explicit version migration.

Test and live environments use distinct base URLs (management-test.adyen.com vs. management-live.adyen.com) and require separate API keys - a key generated in test will not authenticate against live.

SCIM is not a native Adyen capability; it is brokered through IdP integrations at the Enterprise tier, meaning any SCIM-dependent automation outside of Okta must be built against the Management API directly.

Teams managing Adyen alongside a broader SaaS portfolio should evaluate the MCP server with ~100 deep IT/identity integrations as an alternative to maintaining per-app API clients.