Credential overwrites

Credential overwrites let you set credential data globally. This data isn't visible to users, but n8n uses it automatically in the background - for example, to enable OAuth login using a "Connect" button without exposing client secrets.

In the Editor UI, n8n hides all overwritten fields by default, so users can authenticate with OAuth using the "Connect" button on the credential.

For the environment variables used to configure credential overwrites, refer to Credentials environment variables.

Watch a tutorial on credential overwrites, including how to set them up using the REST API with a ready-made workflow template:

Using environment variables

Set CREDENTIALS_OVERWRITE_DATA to { CREDENTIAL_NAME: { PARAMETER: VALUE }}.

This approach isn't recommended. Environment variables aren't protected in n8n, so the data can leak to users.

Using the REST API

The recommended approach is to load the data using a custom REST endpoint.

1. Set CREDENTIALS_OVERWRITE_ENDPOINT to the path where the endpoint should be available:

   export CREDENTIALS_OVERWRITE_ENDPOINT=send-credentials

   Optionally, set CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN to require a bearer token for accessing the endpoint.

   Without an auth token, the endpoint can only be called once for security reasons.

2. Prepare a JSON file with the credentials to overwrite. For example, oauth-credentials.json for Asana and GitHub:

   {
       "asanaOAuth2Api": {
           "clientId": "<id>",
           "clientSecret": "<secret>"
       },
       "githubOAuth2Api": {
           "clientId": "<id>",
           "clientSecret": "<secret>"
       }
   }

3. Send the file to your n8n instance:

   curl -H "Content-Type: application/json" --data @oauth-credentials.json http://localhost:5678/send-credentials

   If CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN is set to secure-token:

   curl -H "Content-Type: application/json" -H "Authorization: Bearer secure-token" --data @oauth-credentials.json http://localhost:5678/send-credentials

Credentials can extend other credentials. For example, googleSheetsOAuth2Api extends googleOAuth2Api. You can set parameters on the parent (googleOAuth2Api) and all child credentials will use them.

Show OAuth scope fields

By default, n8n hides scope fields when managed OAuth is available. To let users configure scopes for specific managed OAuth credential types, set N8N_MANAGED_OAUTH_SHOW_SCOPES to a comma-separated list:

export N8N_MANAGED_OAUTH_SHOW_SCOPES=googleOAuth2Api

This setting applies only to the credential types you list. It doesn't apply to credential types that extend a listed type.

Letting users set their own scopes can break verified OAuth apps. Many providers, such as Google, require you to define and justify every scope your app requests during app verification. If a user adds a scope you didn't declare, the provider may suspend or ban your app. Only enable this setting for credential types where users adding scopes won't put your app's verification at risk.

Persistence

To store credential overwrites in the database and propagate them to all workers in multi-instance or queue mode, enable:

export CREDENTIALS_OVERWRITE_PERSISTENCE=true

When enabled, n8n stores the encrypted overwrites in the settings table and broadcasts a reload-overwrite-credentials event so workers reload the latest values. When disabled, overwrites remain in memory on the process that loaded them and n8n doesn't propagate them to workers or preserve them across restarts.

Related resources

• Manage credentials

• Share credentials securely

• End-user credentials

• Use external secret stores