Credentials API

Manage third-party service credentials used by workflow nodes. Credentials are encrypted at rest and scoped to a team. All endpoints require the BUILDER role.

Encryption

Credential secrets are encrypted before storage. The API never returns raw secret values -- only metadata and masked previews.

List Credentials

GET

/api/credentials

List all credentials for the current team (requires BUILDER role)

Query Parameters

Parameter	Type	Required	Description
`teamId`	UUID	Yes	The team to list credentials for
`type`	string	No	Filter by credential type (e.g. OPENAI, SLACK, SMTP)

Response

200 OK

[
  {
    "id": "uuid",
    "name": "Production OpenAI Key",
    "type": "OPENAI",
    "createdAt": "2026-02-17T10:00:00.000Z",
    "updatedAt": "2026-02-17T10:00:00.000Z",
    "lastTestedAt": "2026-02-17T12:00:00.000Z",
    "testStatus": "SUCCESS"
  },
  {
    "id": "uuid",
    "name": "Slack Bot Token",
    "type": "SLACK",
    "createdAt": "2026-02-15T08:00:00.000Z",
    "updatedAt": "2026-02-15T08:00:00.000Z",
    "lastTestedAt": null,
    "testStatus": null
  }
]

Create Credential

POST

/api/credentials

Create a new credential (requires BUILDER role)

Request Body

Field	Type	Required	Description
`name`	string	Yes	A descriptive name for the credential
`type`	string	Yes	Credential type (e.g. OPENAI, SLACK, SMTP, HTTP_BASIC, etc.)
`teamId`	UUID	Yes	Team the credential belongs to
`data`	object	Yes	Credential-specific key-value pairs (encrypted at rest)

Request

{
  "name": "Production OpenAI Key",
  "type": "OPENAI",
  "teamId": "uuid",
  "data": {
    "apiKey": "sk-..."
  }
}

Response

201 Created

{
  "id": "uuid",
  "name": "Production OpenAI Key",
  "type": "OPENAI",
  "teamId": "uuid",
  "createdAt": "2026-02-17T10:00:00.000Z"
}

Secret handling

The data object is write-only. Once saved, the API will never return raw secret values. Update the credential to change secrets.

Test Credential

POST

/api/credentials/{id}/test?teamId={uuid}

Test a credential connection (requires BUILDER role)

Path & Query Parameters

Parameter	Type	Description
`id`	UUID	The credential ID to test
`teamId`	UUID	The team context for permission checks

This endpoint attempts to connect to the third-party service using the stored credential data. No request body is required.

Response

200 OK

{
  "status": "SUCCESS",
  "message": "Connection successful",
  "testedAt": "2026-02-17T12:00:00.000Z"
}

200 OK (failure)

{
  "status": "FAILED",
  "message": "Authentication failed: Invalid API key",
  "testedAt": "2026-02-17T12:00:00.000Z"
}

Test before using

Always test credentials after creation to verify the connection works before using them in workflows. A failing credential will cause workflow executions to error.

Supported Credential Types

Type	Required Fields
`OPENAI`	apiKey
`ANTHROPIC`	apiKey
`SLACK`	botToken
`SMTP`	host, port, username, password
`HTTP_BASIC`	username, password
`HTTP_BEARER`	token
`OAUTH2`	clientId, clientSecret, accessToken, refreshToken
`DATABASE`	host, port, database, username, password

Error Codes

Status	Meaning
`400`	Invalid credential data or missing required fields
`403`	Insufficient permissions (requires BUILDER role)
`404`	Credential not found
`409`	Credential name already exists in the team

Executions

Agent Chat