Managing n8n Credentials via the REST API: Create, Delete, Transfer

You provision n8n instances for clients, promote workflows from a dev environment to production, or want to inject API keys from your CI/CD pipeline? Creating every credential by hand in the UI stops scaling past two or three instances. Good news: n8n's public REST API lets you manage credentials programmatically — create them, delete them, transfer them between projects. With one deliberate, healthy limitation: it never lets you read existing secrets back. This guide walks through the endpoints, a complete curl example, and the use cases where this API becomes a game changer.

What the credentials API can (and cannot) do

The n8n public API lives under https://your-instance/api/v1 and authenticates with the X-N8N-API-KEY header. If you do not have a key yet, follow our guide on creating and securing an n8n API key. For credentials, the available operations are:

• POST /api/v1/credentials: create a credential (name, type, data).
• GET /api/v1/credentials/schema/{credentialTypeName}: fetch the JSON schema of a credential type, i.e. the list of expected fields.
• DELETE /api/v1/credentials/{id}: delete a credential you own.
• PUT /api/v1/credentials/{id}/transfer: move a credential to another project (body: {"destinationProjectId": "..."}).

Recent n8n versions add read and update operations (listing credentials, updating an existing one), but with one absolute constant: the response never includes the data field. Secrets are write-only in the official OpenAPI schema. You can push an API key into n8n; you can never read it back.

That is not an oversight — it is security by design: credentials are encrypted at rest with the instance key (N8N_ENCRYPTION_KEY), and a compromised API key must not be enough to exfiltrate every secret on the instance. We cover this model in depth in our article on securing credentials in n8n.

Step 1: fetch the schema of the credential type

Before creating a credential you need two things: the technical name of the type (credentialTypeName) and the fields it expects. The technical name is easy to find by exporting a workflow that already uses that credential: it shows up in the node JSON (githubApi, slackOAuth2Api, postgres…).

The schema itself comes from the API:

curl -X GET \
  "https://your-instance.example.com/api/v1/credentials/schema/freshdeskApi" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

Response (the example n8n documents for freshdeskApi):

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "apiKey": { "type": "string" },
    "domain": { "type": "string" }
  },
  "required": ["apiKey", "domain"]
}

You now know exactly what to send. This discovery mechanism is invaluable for generic provisioning scripts: your tool queries the schema, validates its inputs, then creates the credential.

Step 2: create the credential with POST /api/v1/credentials

Creation takes three required fields: name (the label shown in the UI), type (the technical type name) and data (the object holding the secrets, matching the schema from step 1):

curl -X POST "https://your-instance.example.com/api/v1/credentials" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Freshdesk — Acme client",
    "type": "freshdeskApi",
    "data": {
      "apiKey": "your-freshdesk-key",
      "domain": "acme"
    }
  }'

The response returns the new credential's id, name, type and timestamps — but not data. Save that id: it is what you will reference in workflows imported via the API, and what you will use to delete or transfer the credential later. On recent versions you can also pass a projectId to create the credential directly inside a given project instead of your personal space.

From within n8n itself, the same request works through an HTTP Request node pointing at your second instance — handy when orchestrating provisioning with the n8n REST API to drive your workflows.

Deleting and transferring a credential

Deletion is straightforward:

curl -X DELETE \
  "https://your-instance.example.com/api/v1/credentials/vHxaz5UaCghVYl9C" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

Transferring between projects uses a PUT with the destination project ID:

curl -X PUT \
  "https://your-instance.example.com/api/v1/credentials/vHxaz5UaCghVYl9C/transfer" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destinationProjectId": "VmwOO9HeTEj20kxM"}'

Keep in mind that multiple projects are a paid n8n feature; on a community instance this operation has nothing to act on.

Use cases: when the credentials API becomes essential

• Automated instance provisioning: you deploy one n8n instance per client (white label, agency work) and a script creates the client's SMTP, CRM and database credentials on first boot. Combined with scripted deployment, onboarding drops from two hours to two minutes.
• Dev / staging / prod environments: workflows travel through Git, but secrets must never live there. Your pipeline creates same-named credentials in each environment, pointing at the right systems — the approach we recommend in our guide to dev and prod environments with n8n.
• CI/CD: at deploy time, GitHub Actions injects secrets from your vault (GitHub Secrets, Vault) into the target instance via POST /credentials, then imports the workflows. See our guide on validating n8n workflows in CI with GitHub Actions.
• Secret rotation: when a third-party key gets regenerated, a scheduled workflow updates (or recreates) the matching credential across all your instances, with no manual step.

Best practices: the API does not replace secret hygiene

The main risk is not in the n8n API itself, but in how your scripts handle secrets before sending them. A study by Meli, McNiece and Reaves presented at the 2019 NDSS symposium (How Bad Can It Git? Characterizing Secret Leakage in Public GitHub Repositories) showed that thousands of unique secrets (API keys, private keys) leak every day into public GitHub repositories, affecting more than 100,000 repositories. In the same vein, Rahman, Parnin and Williams found in a 2019 ICSE study of 15,232 infrastructure-as-code scripts (The Seven Sins: Security Smells in Infrastructure as Code Scripts) that hard-coded credentials rank among the most widespread security flaws. In practice:

1. Never put plaintext secrets in your scripts or Git repository — even when you version your n8n workflows with Git, secrets should come from a vault (Vault, GitHub Secrets, encrypted environment variables).
2. Pass values through environment variables at script runtime, like the $N8N_API_KEY in the examples above.
3. One n8n API key per purpose, independently revocable, and only ever sent over HTTPS.
4. Back up N8N_ENCRYPTION_KEY: without it, credentials restored from a backup cannot be decrypted.
5. Check the details against your version: the public API evolves (metadata reads, updates, projectId at creation time); the exact reference for your instance is the OpenAPI schema exposed in the API settings, or the official docs at docs.n8n.io.

Key takeaways

The n8n public API covers the essential credential lifecycle: schema discovery (GET /credentials/schema/{type}), creation (POST /credentials), deletion (DELETE /credentials/{id}) and transfer between projects (PUT /credentials/{id}/transfer), all authenticated with the X-N8N-API-KEY header. By design it never lets you read stored secrets back — the data field is write-only. It is the building block that makes multi-instance provisioning, clean dev/prod separation and CI/CD secret injection possible. The weak link remains your scripts: keep secrets out of code, source them from a vault, and use a dedicated API key per purpose.