credentials.create

Create a new credential on a connection. The API verifies the credential (same checks as the product) before persisting it; if verification fails, nothing is stored.

Facts

POST https://yourinstance.getdx.net/api/connections/:connection_id/credentials.create

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`connection_id`	`Integer`	The connection ID. Substitute this value for `:connection_id` in the URL path. Example: `123`

JSON body (top-level keys)

Name	Type	Description
`label`	`Text`	Display name for the credential. If omitted, a default label is chosen server-side.
`settings`	`JSON`	Non-secret configuration for this credential. Field names and values depend on the connector type (for example, user or account identifiers the connector expects).
`secrets`	`JSON`	Secret values (tokens, passwords, and so on). Keys depend on the connector type.
`expiration_date`	`Date`	Optional. When the credential should be treated as expired, if your workflow uses it.

Usage info

settings and secrets are not identical across connectors. If you want field-level specs for your connector (required keys, formats, examples), contact DX support.

Below is an illustrative Jira Cloud request only—all values are fake placeholders.

Example request (Jira Cloud, fake data)

curl -X POST "https://yourinstance.getdx.net/api/connections/123/credentials.create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  --data '{
    "label": "Automation user — myfakecompany",
    "settings": {
      "jira_user": "dx-automation@myfakecompany.atlassian.net"
    },
    "secrets": {
      "api_token": "ATATT3xFakeExampleToken000000000000000123abc="
    }
  }'

Success response

On success the API returns HTTP 201 with:

{
  "ok": true,
  "credential": {
    "id": 456,
    "type": "jira_cloud",
    "label": "Automation user — myfakecompany",
    "created_at": "2026-04-07T00:00:00.000Z"
  }
}

Errors

This table lists common errors for this method. Other errors can be returned if the service is unavailable or an unexpected failure occurs. Callers should always check the ok field in the response.

Error	Description
`not_authed`	The request did not include a valid API key.
`connection_not_found`	No connection exists for the given `connection_id`.
`invalid_json`	The JSON body could not be parsed.

If verification fails, nothing is stored. The HTTP status code and error label reflect the specific connector error. The response always includes display_message; raw_message is only present when the connector surfaces one.

{
  "ok": false,
  "error": "Invalid credentials",
  "display_message": "The API token provided is invalid.",
  "raw_message": "401 Unauthorized"
}

Common error values:

Error	Description
`Invalid credentials`	The token or password was rejected by the connector.
`Invalid permissions`	The token lacks required scopes or permissions.
`Duplicate secrets`	The provided secrets would duplicate an existing credential.
`Duplicate settings`	The provided settings would duplicate an existing credential.

Connector credential fields

settings and secrets keys vary by connector type. See the connector reference page for the fields accepted by each connector.