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.

SDK token authentication

These endpoints can be authenticated with SDK tokens (Authorization: Bearer sdk_...). Each token has a configurable RBAC role that determines what it can access. Create tokens in Settings → Observability SDK.

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