{"title":"API credentials","category":"default","creationDate":1778842589,"content":"<p>To securely authenticate your requests to Adyen's APIs, you need API credentials. These act as the identity for your integration, and ensures that every request is authorized and linked to the correct account. When your account is set up it includes one API credential. You can also create <a href=\"#multiple-api-credentials\">multiple API credentials<\/a> to improve security and control access.<\/p>\n<p>An API credential consists of:<\/p>\n<ul>\n<li><strong>Username<\/strong>: An identifier in the format <code>ws_123456@Company.[YourCompanyAccount]<\/code>.<\/li>\n<li><strong>API key<\/strong>: A password to authenticate API requests.<\/li>\n<li><strong>Roles<\/strong>: Permissions that define what the credential is allowed to do.<\/li>\n<\/ul>\n<p>API credentials are created automatically during setup. You can manage them within your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>. From there, you can:<\/p>\n<ul>\n<li><a href=\"#create-additional-api-credentials\">Create additional API credentials<\/a><\/li>\n<li><a href=\"#generate-api-key\">Generate an API key<\/a><\/li>\n<li><a href=\"#manage-api-permissions\">Configure API permissions<\/a> by assigning specific roles to your credentials<\/li>\n<\/ul>\n<h2>Requirements<\/h2>\n<p>Before you begin, take into account the following requirements.<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Requirement<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><strong>Integration type<\/strong><\/td>\n<td style=\"text-align: left;\">An Adyen integration.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><strong><a href=\"\/account\/user-roles\">Customer Area roles<\/a><\/strong><\/td>\n<td style=\"text-align: left;\">Make sure that your user account has one of the following <a href=\"\/account\/user-roles\">roles<\/a>:<ul><li markdown=\"1\"><strong>Manage API credentials<\/strong> role<\/li><li markdown=\"1\"><strong>Merchant admin<\/strong> role<\/li><\/ul><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2 id=\"multiple-api-credentials\">Multiple API credentials<\/h2>\n<p>When deciding whether to create multiple API credentials, consider the following trade-offs. Fewer credentials mean fewer API keys to manage, while more credentials provide finer control over permissions and can improve security. For example:<\/p>\n<ul>\n<li>If you have both an online sales channel and a point-of-sale sales channel, we strongly recommend creating a separate API credential for each channel.<\/li>\n<li>If you are doing <a href=\"\/online-payments\/classic-integrations\/modify-payments\/refund#unreferenced-refund\">unreferenced refunds<\/a> for online payments, we strongly recommend creating a separate credential for processing these refunds.<\/li>\n<li>If you have an ecommerce system and a shipping system, you can separate the permissions for initiating and capturing payments.<\/li>\n<\/ul>\n<p>Some merchants also create separate API credentials for different legal entities or different websites. The number of API credentials you create ultimately depends on how you want to structure access and permissions in your integration.<\/p>\n<h2 id=\"create-additional-api-credentials\">Create additional API credentials<\/h2>\n<p>Your account includes default API credentials with the default account scopes:<\/p>\n<ul>\n<li>Credentials created on a company account can access the company account, including all linked merchant accounts.<\/li>\n<li>Credentials created on a merchant account can only access that merchant account.<\/li>\n<\/ul>\n<p>You can create additional credentials and control their <a href=\"#manage-api-scope\">account scope<\/a> to better manage your integration.<\/p>\n<p>To create a new API credential:<\/p>\n<ol>\n<li>Log in to your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a> and select your <strong>Company<\/strong> account.<\/li>\n<li>Go to <strong>Developers<\/strong>\u00a0&gt;\u00a0<strong>API credentials<\/strong>.<br \/>\nThis opens a list with all API credentials linked to your company account.<\/li>\n<li>Select the <strong>Payments<\/strong> or <strong>Platforms<\/strong> tab, depending on your integration type.<\/li>\n<li>Select <i class=\"adl-icon-add\" role=\"img\" aria-label=\"add icon\"><\/i> <strong>Create new credential<\/strong>.<\/li>\n<li>In the <strong>Create API credential<\/strong> dialog, under <strong>Credential type<\/strong>, select <strong>Web service user<\/strong>.<\/li>\n<li>Optional. In the <strong>Description<\/strong> field, describe the purpose of the credential.<\/li>\n<li>Select <strong>Create credential<\/strong>.<\/li>\n<li>On the <strong>Configure API credentials<\/strong> page, save the generated <strong>Username<\/strong>, for example, <span translate=\"no\"><strong>ws_123456@Company.<\/strong><\/span><strong>[YourCompanyAccount]<\/strong>.<\/li>\n<li>Under <strong>Server settings<\/strong> &gt; <strong>Authentication<\/strong> select the <strong>API key<\/strong> tab.<\/li>\n<li>Select <strong>Generate API key<\/strong>.<\/li>\n<li>Select the copy icon <i class=\"adl-icon-copy\"><\/i> and store your API key securely in your system.<\/li>\n<li>Select <strong>Save changes<\/strong>.<\/li>\n<\/ol>\n<h2 id=\"generate-api-key\">Generate an API key<\/h2>\n<p>Use <a href=\"\/development-resources\/api-authentication#api-key-authentication\">API keys to authenticate your requests<\/a>.<\/p>\n<p>You can generate a new API key at any time, for example if a key is lost or compromised. When you generate a new API key, it becomes active immediately. The previous key remains active for 24 hours to allow you to update your systems.<\/p>\n<p>To generate your API key:<\/p>\n<ol>\n<li>Log in to your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a> and select your <strong>Company<\/strong> account.<\/li>\n<li>Go to <strong>Developers<\/strong> &gt; <strong>API credentials<\/strong>.<\/li>\n<li>Select the <strong>Payments<\/strong> or <strong>Platforms<\/strong> tab, depending on your integration type.<\/li>\n<li>Select the credential username.<\/li>\n<li>Under <strong>Server settings<\/strong> &gt; <strong>Authentication<\/strong> select the <strong>API key<\/strong> tab.<\/li>\n<li>Select <strong>Generate API key<\/strong>.<\/li>\n<li>Select the copy icon <i class=\"adl-icon-copy\"><\/i> and store your API key securely in your system.\n<div class=\"notices yellow\">\n<p>You cannot copy the API key again after you leave the page.<\/p>\n<\/div><\/li>\n<li>Select <strong>Save changes<\/strong>.<\/li>\n<\/ol>\n<div class=\"notices green\">\n<p>When you switch to your live environment, you must generate a new API key in your <a href=\"https:\/\/ca-live.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">live Customer Area<\/a>.<\/p>\n<\/div>\n<h2 id=\"basic-authentication\">Generate a basic authentication password<\/h2>\n<p>If you are using <a href=\"\/development-resources\/api-authentication#using-basic-authentication\">basic authentication<\/a> to authenticate your API requests, you can generate a basic authentication password for your API credential.<\/p>\n<div class=\"notices red\">\n<p>When you generate a new basic authentication password, the previous password is deactivated immediately.<\/p>\n<\/div>\n<p>If you want to continue using your existing password while updating your systems, you can instead <a href=\"#create-additional-api-credentials\">create a new API credential<\/a>. This allows both credentials to remain active until you have updated your systems.<\/p>\n<p>To generate a basic authentication password:<\/p>\n<ol>\n<li>Log in to your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>.<\/li>\n<li>Go to <strong>Developers<\/strong> &gt; <strong>API credentials<\/strong>.<br \/>\nA list appears with all API credentials linked to your company account.<\/li>\n<li>Select the <strong>Payments<\/strong> or <strong>Platforms<\/strong> tab, depending on your integration type.<\/li>\n<li>Select the credential username you want to generate the password for.<\/li>\n<li>On the <strong>Configure API credential<\/strong> page, in the <strong>Server settings<\/strong> section, select <strong>Basic auth<\/strong>.<\/li>\n<li>Select <strong>Generate password<\/strong>.<\/li>\n<li>Select the copy icon <i class=\"adl-icon-copy\"><\/i> and store your basic authentication password securely in your system.<\/li>\n<li>Select <strong>Save changes<\/strong>.<\/li>\n<\/ol>\n<div class=\"notices green\">\n<p>When you switch to your live environment, use the basic authentication credentials from your <a href=\"https:\/\/ca-live.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">live Customer Area<\/a>.<\/p>\n<\/div>\n<h2 id=\"manage-api-permissions\">Manage API permissions<\/h2>\n<p>Permissions for a API credential are defined by its enabled <a href=\"\/development-resources\/api-credentials\/roles\">roles<\/a>. An API credential must have at least one enabled role.<\/p>\n<p>To manage API permissions:<\/p>\n<ol>\n<li>Log in to your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a> and select your <strong>Company<\/strong> account.<\/li>\n<li>Go to <strong>Developers<\/strong> &gt; <strong>API credentials<\/strong>.<\/li>\n<li>Select the <strong>Payments<\/strong> or <strong>Platforms<\/strong> tab, depending on your integration type.<\/li>\n<li>Select the credential username.<\/li>\n<li>On the <strong>Configure API credential<\/strong> page, under <strong>Permissions<\/strong>, expand the categories to see the lists of available roles.<br \/>\nYou can also use the search bar to find specific roles.<\/li>\n<li>Select the checkboxes of the roles you want to enable for the API credential.<\/li>\n<li>Select <strong>Save changes<\/strong>.<\/li>\n<\/ol>\n<h2 id=\"manage-api-scope\">Manage API credential account scope<\/h2>\n<p>The scope of an API credential is determined by the account where it is created. By default, the following applies:<\/p>\n<ul>\n<li>Credentials created on a company account can access the company account, including all linked merchant accounts.<\/li>\n<li>Credentials created on a merchant account can only access that merchant account.<\/li>\n<\/ul>\n<p>To manage the API account scope:<\/p>\n<ol>\n<li>\n<p>Log in to your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a> and select your <strong>Company<\/strong> account.<\/p>\n<\/li>\n<li>\n<p>Go to <strong>Developers<\/strong> &gt; <strong>API credentials<\/strong>.<\/p>\n<\/li>\n<li>\n<p>Select the <strong>Payments<\/strong> or <strong>Platforms<\/strong> tab, depending on your integration type.<\/p>\n<\/li>\n<li>\n<p>Select the credential username.<\/p>\n<\/li>\n<li>\n<p>On the <strong>Configure API credential<\/strong> page, under <strong>Accounts<\/strong>, expand the category to see the available options:<\/p>\n<ul>\n<li><strong>Company account and all associated merchant accounts<\/strong><\/li>\n<li><strong>Only selected account groups and merchant accounts<\/strong><\/li>\n<\/ul>\n<p>You can also use the search bar to locate specific accounts, then select the checkboxes for the accounts you want the API credential to access.<\/p>\n<\/li>\n<li>\n<p>Select <strong>Save changes<\/strong>.<\/p>\n<\/li>\n<\/ol>\n<h2 id=\"reset-api-key\">Reset the expiry time of a previous API key<\/h2>\n<p>You can reset the expiry time of a previous API key by following these steps:<\/p>\n<ol>\n<li>Log in to your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a> and select your <strong>Company<\/strong> account.<\/li>\n<li>Go to <strong>Developers<\/strong> &gt; <strong>API credentials<\/strong>.<\/li>\n<li>Select the <strong>Payments<\/strong> or <strong>Platforms<\/strong> tab, depending on your integration type.<\/li>\n<li>Select the credential username.<\/li>\n<li>On the <strong>Configure API credential<\/strong> page, in the <strong>Server settings<\/strong> section, select <strong>API key<\/strong>.<\/li>\n<li>Under <strong>Expiring keys<\/strong>, see how much time is left until the previous key expires, and then either:\n<ul>\n<li>Select the reset icon <i class=\"adl-icon-rotate-right\"><\/i> to reset the expiry time to 24 hours.<\/li>\n<li>Select the expire now icon <i class=\"adl-icon-bin\"><\/i> to expire the previous key immediately.<\/li>\n<\/ul><\/li>\n<li>Select <strong>Save changes<\/strong>.<\/li>\n<\/ol>\n<h2>Add an allowed IP range<\/h2>\n<p>As a security measure, you can add allowed IP addresses to your API credential. When you add an allowed IP range, only requests originating from that range will be permitted.<\/p>\n<p>To add allowed IP addresses:<\/p>\n<ol>\n<li>Log in to your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>.<\/li>\n<li>Go to <strong>Developers<\/strong> &gt; <strong>API credentials<\/strong>.<\/li>\n<li>Select the <strong>Payments<\/strong> or <strong>Platforms<\/strong> tab, depending on your integration type.<\/li>\n<li>Select the credential username.<\/li>\n<li>Under <strong>Server settings<\/strong>, select <strong>Allowed IP range<\/strong>.<\/li>\n<li>Add IP addresses that you want to allow access from.<\/li>\n<li>Select <strong>Save changes<\/strong>.<\/li>\n<\/ol>\n<h2>Deactivate an API credential<\/h2>\n<p>API credentials cannot be deleted. However, you can deactivate a credential to prevent its API keys from being used. To deactivate an API credential:<\/p>\n<ol>\n<li>Log in to your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>.<\/li>\n<li>Go to <strong>Developers<\/strong> &gt; <strong>API credentials<\/strong>.<\/li>\n<li>Select the <strong>Payments<\/strong> or <strong>Platforms<\/strong> tab, depending on your integration type.<\/li>\n<li>Select the credential username.<\/li>\n<li>Under <strong>General Settings<\/strong> use the toggle to switch the webservice user to <strong>Inactive<\/strong>.<\/li>\n<li>Select <strong>Save changes<\/strong>.<\/li>\n<\/ol>\n<p>This change takes effect immediately and prevents the processing of API requests with this credential. You can switch it back to <strong>Active<\/strong> at any time to allow API requests again.<\/p>\n<h2>See also<\/h2>\n<div class=\"see-also-links output-inline\" id=\"see-also\">\n<ul><li><a href=\"\/online-payments\"\n                        target=\"_self\"\n                        >\n                    Online payments\n                <\/a><\/li><li><a href=\"\/point-of-sale\"\n                        target=\"_self\"\n                        >\n                    In-person payments\n                <\/a><\/li><li><a href=\"\/development-resources\/pci-dss-compliance-guide\"\n                        target=\"_self\"\n                        >\n                    PCI DSS compliance guide\n                <\/a><\/li><li><a href=\"\/development-resources\/client-side-authentication\"\n                        target=\"_self\"\n                        >\n                    Client-side authentication\n                <\/a><\/li><\/ul><\/div>\n","url":"https:\/\/docs.adyen.com\/development-resources\/api-credentials","articleFields":{"description":"Generate and configure credentials for the API requests that you make to Adyen.","feedback_component":true,"id":"34120911","type":"page","_expandable":{"operations":""},"status":"current","last_edit_on":"06-08-2021 10:58","page_id":"f1b6aefe-7b71-44de-b42a-378f3b0516c7","filters_component":false,"decision_tree":"[]"},"algolia":{"url":"https:\/\/docs.adyen.com\/development-resources\/api-credentials","title":"API credentials","content":"To securely authenticate your requests to Adyen's APIs, you need API credentials. These act as the identity for your integration, and ensures that every request is authorized and linked to the correct account. When your account is set up it includes one API credential. You can also create multiple API credentials to improve security and control access.\nAn API credential consists of:\n\nUsername: An identifier in the format ws_123456@Company.[YourCompanyAccount].\nAPI key: A password to authenticate API requests.\nRoles: Permissions that define what the credential is allowed to do.\n\nAPI credentials are created automatically during setup. You can manage them within your Customer Area. From there, you can:\n\nCreate additional API credentials\nGenerate an API key\nConfigure API permissions by assigning specific roles to your credentials\n\nRequirements\nBefore you begin, take into account the following requirements.\n\n\n\nRequirement\nDescription\n\n\n\n\nIntegration type\nAn Adyen integration.\n\n\nCustomer Area roles\nMake sure that your user account has one of the following roles:Manage API credentials roleMerchant admin role\n\n\n\nMultiple API credentials\nWhen deciding whether to create multiple API credentials, consider the following trade-offs. Fewer credentials mean fewer API keys to manage, while more credentials provide finer control over permissions and can improve security. For example:\n\nIf you have both an online sales channel and a point-of-sale sales channel, we strongly recommend creating a separate API credential for each channel.\nIf you are doing unreferenced refunds for online payments, we strongly recommend creating a separate credential for processing these refunds.\nIf you have an ecommerce system and a shipping system, you can separate the permissions for initiating and capturing payments.\n\nSome merchants also create separate API credentials for different legal entities or different websites. The number of API credentials you create ultimately depends on how you want to structure access and permissions in your integration.\nCreate additional API credentials\nYour account includes default API credentials with the default account scopes:\n\nCredentials created on a company account can access the company account, including all linked merchant accounts.\nCredentials created on a merchant account can only access that merchant account.\n\nYou can create additional credentials and control their account scope to better manage your integration.\nTo create a new API credential:\n\nLog in to your Customer Area and select your Company account.\nGo to Developers\u00a0&gt;\u00a0API credentials.\nThis opens a list with all API credentials linked to your company account.\nSelect the Payments or Platforms tab, depending on your integration type.\nSelect  Create new credential.\nIn the Create API credential dialog, under Credential type, select Web service user.\nOptional. In the Description field, describe the purpose of the credential.\nSelect Create credential.\nOn the Configure API credentials page, save the generated Username, for example, ws_123456@Company.[YourCompanyAccount].\nUnder Server settings &gt; Authentication select the API key tab.\nSelect Generate API key.\nSelect the copy icon  and store your API key securely in your system.\nSelect Save changes.\n\nGenerate an API key\nUse API keys to authenticate your requests.\nYou can generate a new API key at any time, for example if a key is lost or compromised. When you generate a new API key, it becomes active immediately. The previous key remains active for 24 hours to allow you to update your systems.\nTo generate your API key:\n\nLog in to your Customer Area and select your Company account.\nGo to Developers &gt; API credentials.\nSelect the Payments or Platforms tab, depending on your integration type.\nSelect the credential username.\nUnder Server settings &gt; Authentication select the API key tab.\nSelect Generate API key.\nSelect the copy icon  and store your API key securely in your system.\n\nYou cannot copy the API key again after you leave the page.\n\nSelect Save changes.\n\n\nWhen you switch to your live environment, you must generate a new API key in your live Customer Area.\n\nGenerate a basic authentication password\nIf you are using basic authentication to authenticate your API requests, you can generate a basic authentication password for your API credential.\n\nWhen you generate a new basic authentication password, the previous password is deactivated immediately.\n\nIf you want to continue using your existing password while updating your systems, you can instead create a new API credential. This allows both credentials to remain active until you have updated your systems.\nTo generate a basic authentication password:\n\nLog in to your Customer Area.\nGo to Developers &gt; API credentials.\nA list appears with all API credentials linked to your company account.\nSelect the Payments or Platforms tab, depending on your integration type.\nSelect the credential username you want to generate the password for.\nOn the Configure API credential page, in the Server settings section, select Basic auth.\nSelect Generate password.\nSelect the copy icon  and store your basic authentication password securely in your system.\nSelect Save changes.\n\n\nWhen you switch to your live environment, use the basic authentication credentials from your live Customer Area.\n\nManage API permissions\nPermissions for a API credential are defined by its enabled roles. An API credential must have at least one enabled role.\nTo manage API permissions:\n\nLog in to your Customer Area and select your Company account.\nGo to Developers &gt; API credentials.\nSelect the Payments or Platforms tab, depending on your integration type.\nSelect the credential username.\nOn the Configure API credential page, under Permissions, expand the categories to see the lists of available roles.\nYou can also use the search bar to find specific roles.\nSelect the checkboxes of the roles you want to enable for the API credential.\nSelect Save changes.\n\nManage API credential account scope\nThe scope of an API credential is determined by the account where it is created. By default, the following applies:\n\nCredentials created on a company account can access the company account, including all linked merchant accounts.\nCredentials created on a merchant account can only access that merchant account.\n\nTo manage the API account scope:\n\n\nLog in to your Customer Area and select your Company account.\n\n\nGo to Developers &gt; API credentials.\n\n\nSelect the Payments or Platforms tab, depending on your integration type.\n\n\nSelect the credential username.\n\n\nOn the Configure API credential page, under Accounts, expand the category to see the available options:\n\nCompany account and all associated merchant accounts\nOnly selected account groups and merchant accounts\n\nYou can also use the search bar to locate specific accounts, then select the checkboxes for the accounts you want the API credential to access.\n\n\nSelect Save changes.\n\n\nReset the expiry time of a previous API key\nYou can reset the expiry time of a previous API key by following these steps:\n\nLog in to your Customer Area and select your Company account.\nGo to Developers &gt; API credentials.\nSelect the Payments or Platforms tab, depending on your integration type.\nSelect the credential username.\nOn the Configure API credential page, in the Server settings section, select API key.\nUnder Expiring keys, see how much time is left until the previous key expires, and then either:\n\nSelect the reset icon  to reset the expiry time to 24 hours.\nSelect the expire now icon  to expire the previous key immediately.\n\nSelect Save changes.\n\nAdd an allowed IP range\nAs a security measure, you can add allowed IP addresses to your API credential. When you add an allowed IP range, only requests originating from that range will be permitted.\nTo add allowed IP addresses:\n\nLog in to your Customer Area.\nGo to Developers &gt; API credentials.\nSelect the Payments or Platforms tab, depending on your integration type.\nSelect the credential username.\nUnder Server settings, select Allowed IP range.\nAdd IP addresses that you want to allow access from.\nSelect Save changes.\n\nDeactivate an API credential\nAPI credentials cannot be deleted. However, you can deactivate a credential to prevent its API keys from being used. To deactivate an API credential:\n\nLog in to your Customer Area.\nGo to Developers &gt; API credentials.\nSelect the Payments or Platforms tab, depending on your integration type.\nSelect the credential username.\nUnder General Settings use the toggle to switch the webservice user to Inactive.\nSelect Save changes.\n\nThis change takes effect immediately and prevents the processing of API requests with this credential. You can switch it back to Active at any time to allow API requests again.\nSee also\n\n\n                    Online payments\n                \n                    In-person payments\n                \n                    PCI DSS compliance guide\n                \n                    Client-side authentication\n                \n","type":"page","locale":"en","boost":18,"hierarchy":{"lvl0":"Home","lvl1":"Development resources","lvl2":"API credentials"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/development-resources","lvl2":"\/development-resources\/api-credentials"},"levels":3,"category":"Development Resources","category_color":"green","tags":["credentials"]}}