Create credential

POST https://app.sulus.ai/api/tools/credentials

Create a personal server-auth credential

Authentication

Send a bearer token created on your dashboard's Developer page:

Authorization: Bearer <YOUR_API_KEY>

Request body

provider string Required

Credential kind. Defaults to custom-credential when omitted.

Validation: required|string|in:custom-credential,webhook

name string Optional Nullable

Display name.

Validation: nullable|string|max:40

authenticationPlan object Required

The auth configuration — shape depends on type.

Validation: required|array

authenticationPlan.type string Required

Immutable after creation — update rejects a differing type.

Validation: required|string|in:bearer,oauth2,hmac

authenticationPlan.token string Optional Nullable

Bearer token value.

Validation: required when type=bearer

authenticationPlan.headerName string Optional Nullable

bearer only — defaults to Authorization.

Validation: nullable|string

authenticationPlan.bearerPrefixEnabled boolean Optional Nullable

bearer only.

Validation: nullable|boolean

authenticationPlan.url string Optional Nullable

OAuth2 token URL.

Validation: required when type=oauth2

authenticationPlan.clientId string Optional Nullable

Validation: required when type=oauth2

authenticationPlan.clientSecret string Optional Nullable

Validation: required when type=oauth2

authenticationPlan.scope string Optional Nullable

oauth2 only.

Validation: nullable|string

authenticationPlan.secretKey string Optional Nullable

Validation: required when type=hmac

authenticationPlan.algorithm string Optional Nullable

Validation: required when type=hmac

authenticationPlan.signatureHeader string Optional Nullable

hmac only.

Validation: nullable|string

authenticationPlan.signaturePrefix string Optional Nullable

hmac only.

Validation: nullable|string

authenticationPlan.timestampHeader string Optional Nullable

hmac only.

Validation: nullable|string

authenticationPlan.messageIdHeader string Optional Nullable

hmac only.

Validation: nullable|string

authenticationPlan.includeTimestamp boolean Optional Nullable

hmac only.

Validation: nullable|boolean

authenticationPlan.payloadFormat string Optional Nullable

hmac only.

Validation: nullable|string

authenticationPlan.signatureEncoding string Optional Nullable

hmac only.

Validation: nullable|string

authenticationPlan.secretIsBase64 boolean Optional Nullable

hmac only.

Validation: nullable|boolean

encryptionPlan object Optional Nullable

Optional public-key encryption for the stored secret.

Validation: nullable|array

encryptionPlan.publicKey string Optional Nullable

Requests are encrypted with this key before being sent.

Validation: nullable — PEM-formatted public key

Errors

Status	Meaning	Body
`401`	No authenticated user	`{"success":false,"message":"Unauthenticated."}`
`422`	Missing per-type required fields	`{"success":false,"message":"Token is required."}`
`502`	Live credential creation failed	`{"success":false,"message":"<cleaned upstream error>"}`
`422`	Validation failed	`{"message":"…","errors":{"field":["…"]}}`
`403`	Feature tools not enabled for the account

Notes

provider defaults to custom-credential when omitted.
Required fields per authenticationPlan.type: bearer → token; oauth2 → url, clientId, clientSecret; hmac → secretKey, algorithm.
A new credential is always status: active.
Raw connectivity/DNS errors from the live validation step are cleaned into a generic actionable message before being returned.

curl --request POST \
  --url https://app.sulus.ai/api/tools/credentials \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "custom-credential",
  "name": "Orders API",
  "authenticationPlan": {
    "type": "bearer",
    "token": "sk_live_51Hxxxxxxxxxxxxxxxxxxxxxxxx",
    "bearerPrefixEnabled": true
  }
}'

import requests

url = "https://app.sulus.ai/api/tools/credentials"
headers = {"Authorization": "Bearer <YOUR_API_KEY>"}
payload = {
  "provider": "custom-credential",
  "name": "Orders API",
  "authenticationPlan": {
    "type": "bearer",
    "token": "sk_live_51Hxxxxxxxxxxxxxxxxxxxxxxxx",
    "bearerPrefixEnabled": true
  }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://app.sulus.ai/api/tools/credentials"
	payload := strings.NewReader(`{
  "provider": "custom-credential",
  "name": "Orders API",
  "authenticationPlan": {
    "type": "bearer",
    "token": "sk_live_51Hxxxxxxxxxxxxxxxxxxxxxxxx",
    "bearerPrefixEnabled": true
  }
}`)
	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
	req.Header.Add("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Response 200

{
    "success": true,
    "data": {
        "id": "3f9c2a10-6b4e-4a2d-9f0a-1c2d3e4f5a6b",
        "provider": "custom-credential",
        "name": "Orders API",
        "auth_type": "bearer",
        "encryption_enabled": false,
        "status": "active"
    }
}

{
    "success": true,
    "data": {
        "id": "3f9c2a10-6b4e-4a2d-9f0a-1c2d3e4f5a6b",
        "provider": "custom-credential",
        "name": "Orders API",
        "auth_type": "bearer",
        "encryption_enabled": false,
        "status": "active"
    }
}