Credentials API

API endpoints for managing credentials securely.

Overview

Credentials store sensitive authentication data (API keys, passwords, tokens) for use in workflow nodes. Credentials are encrypted at rest.

Security Note

Credential values are never returned in API responses. Only metadata is returned.

---

List Credentials

Retrieve all credentials (metadata only).

GET /api/v1/credentials

Query Parameters

Parameter	Type	Description
type	string	Filter by credential type

Example Request

curl http://localhost:8080/api/v1/credentials \
  -H "Authorization: Bearer <token>"

Response

{
  "data": [
    {
      "id": "cred-123",
      "name": "Production API Key",
      "type": "apiKey",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T00:00:00Z"
    },
    {
      "id": "cred-456",
      "name": "Slack Webhook",
      "type": "slackWebhook",
      "createdAt": "2024-01-10T00:00:00Z",
      "updatedAt": "2024-01-10T00:00:00Z"
    }
  ],
  "total": 2
}

---

Get Credential

Retrieve credential metadata (not the secret values).

GET /api/v1/credentials/{id}

Example Request

curl http://localhost:8080/api/v1/credentials/cred-123 \
  -H "Authorization: Bearer <token>"

Response

{
  "id": "cred-123",
  "name": "Production API Key",
  "type": "apiKey",
  "fields": ["apiKey"],
  "nodesUsing": [
    {
      "workflowId": "wf-123",
      "workflowName": "Data Sync",
      "nodeId": "http-1",
      "nodeName": "API Request"
    }
  ],
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T00:00:00Z"
}

---

Create Credential

Create a new credential.

POST /api/v1/credentials

Request Body

Field	Type	Required	Description
name	string	Yes	Display name
type	string	Yes	Credential type
data	object	Yes	Credential values

Credential Types

Type	Fields
apiKey	apiKey
basicAuth	username, password
oauth2	accessToken, refreshToken, clientId, clientSecret
slackWebhook	webhookUrl
slackApi	token
awsCredentials	accessKeyId, secretAccessKey, region
postgresCredentials	host, port, database, user, password
smtpCredentials	host, port, user, password

Example Request

curl -X POST http://localhost:8080/api/v1/credentials \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Key",
    "type": "apiKey",
    "data": {
      "apiKey": "sk-abc123def456"
    }
  }'

Response

{
  "id": "cred-789",
  "name": "My API Key",
  "type": "apiKey",
  "createdAt": "2024-01-26T16:00:00Z"
}

---

Update Credential

Update credential values.

PUT /api/v1/credentials/{id}

Request Body

{
  "name": "Updated Name",
  "data": {
    "apiKey": "new-api-key-value"
  }
}

Example Request

curl -X PUT http://localhost:8080/api/v1/credentials/cred-123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated API Key",
    "data": {
      "apiKey": "sk-new-key-value"
    }
  }'

Response

{
  "id": "cred-123",
  "name": "Updated API Key",
  "type": "apiKey",
  "updatedAt": "2024-01-26T16:00:00Z"
}

---

Delete Credential

Delete a credential.

DELETE /api/v1/credentials/{id}

Example Request

curl -X DELETE http://localhost:8080/api/v1/credentials/cred-123 \
  -H "Authorization: Bearer <token>"

Response

204 No Content

Error: Credential In Use

{
  "error": "Credential is in use by workflows",
  "code": "CREDENTIAL_IN_USE",
  "details": {
    "workflows": ["Data Sync", "Daily Report"]
  }
}

Use ?force=true to delete anyway:

curl -X DELETE "http://localhost:8080/api/v1/credentials/cred-123?force=true" \
  -H "Authorization: Bearer <token>"

---

Test Credential

Test if credential values are valid.

POST /api/v1/credentials/{id}/test

Example Request

curl -X POST http://localhost:8080/api/v1/credentials/cred-123/test \
  -H "Authorization: Bearer <token>"

Response (Success)

{
  "valid": true,
  "message": "Credential is valid"
}

Response (Failure)

{
  "valid": false,
  "message": "Authentication failed",
  "details": {
    "error": "Invalid API key"
  }
}

---

Using Credentials in Workflows

Reference credentials in node parameters:

{
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "url": "https://api.example.com/data",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer {{ $credentials.myApiKey.apiKey }}"
    }
  },
  "credentials": {
    "myApiKey": "cred-123"
  }
}

---

Credential Type Examples

API Key

{
  "name": "OpenAI API Key",
  "type": "apiKey",
  "data": {
    "apiKey": "sk-..."
  }
}

Basic Auth

{
  "name": "Service Login",
  "type": "basicAuth",
  "data": {
    "username": "[email protected]",
    "password": "secret123"
  }
}

AWS Credentials

{
  "name": "AWS Production",
  "type": "awsCredentials",
  "data": {
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1"
  }
}

Database

{
  "name": "Production Database",
  "type": "postgresCredentials",
  "data": {
    "host": "db.example.com",
    "port": 5432,
    "database": "myapp",
    "user": "appuser",
    "password": "secret123"
  }
}

---

Error Responses

400 Bad Request

{
  "error": "Invalid credential data",
  "code": "VALIDATION_ERROR",
  "details": {
    "apiKey": "required field missing"
  }
}

404 Not Found

{
  "error": "Credential not found",
  "code": "NOT_FOUND"
}

---

See Also

• Credentials Guide - Credential management
• Credential Types - All credential types