Skip to main content
POST
/
credentials
Create Credential
curl --request POST \
  --url https://api.example.com/credentials \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "vaultIntegrationId": "<string>",
  "vaultPath": "<string>",
  "fieldMap": {
    "fieldMap.username": "<string>",
    "fieldMap.password": "<string>",
    "fieldMap.totp": "<string>"
  },
  "allowedDomains": [
    "<string>"
  ]
}
'
{
  "id": "<string>",
  "name": "<string>",
  "vaultIntegrationId": "<string>",
  "vaultPath": "<string>",
  "fieldMap": {},
  "allowedDomains": [
    "<string>"
  ],
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

​
Overview

Registers a named credential that the authenticate task action can resolve at run time. The raw username/password never touch ScrapEngine — only the vault integration ID, the path inside your vault, and the field names to read are stored here. Each credential is scoped to one or more hostnames via allowedDomains; the authenticate action refuses to use a credential on any other host.

​
Body

​
name
string
required
Human-readable name. 1-100 characters.
​
vaultIntegrationId
string
required
UUID of the vault integration that will be used to read the secret. Created via POST /vault-integrations.
​
vaultPath
string
required
Path inside your vault. For HashiCorp KV v2 use the logical path (for example secret/data/login-alice).
​
fieldMap
object
required
Maps the field names stored inside the vault secret to the roles the authenticate action understands.
​
allowedDomains
string[]
required
Hostnames this credential may be used on. At least one entry is required. Plain entries match the exact hostname; *.example.com matches subdomains but NOT the bare host. Wildcard-only (*) is rejected.

​
Example Request

curl -X POST "https://api.scrapengine.io/api/v1/credentials" \
  -H "Authorization: Bearer $SCRAPENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice @ app.example.com",
    "vaultIntegrationId": "5f8c6a74-5f2e-4f5a-9e58-5b9c3c7d2a11",
    "vaultPath": "secret/data/login-alice",
    "fieldMap": {
      "username": "username",
      "password": "password",
      "totp": "totp_seed"
    },
    "allowedDomains": ["app.example.com", "*.internal.example.com"]
  }'

​
Response

​
Success Response (201)

​
id
string
Credential ID (UUID). Reference this from the authenticate task action.
​
name
string
The name you provided.
​
vaultIntegrationId
string
The vault integration this credential reads from.
​
vaultPath
string
The vault path this credential reads from.
​
fieldMap
object
The stored field-name mapping, echoed back.
​
allowedDomains
string[]
The stored allow-list of hostnames, echoed back.
​
createdAt
string
ISO 8601 timestamp.
​
updatedAt
string
ISO 8601 timestamp.
Example Response: 
{
  "id": "2b5aa4c8-b9e6-4e58-9c80-1d4bfd0a3f01",
  "name": "Alice @ app.example.com",
  "vaultIntegrationId": "5f8c6a74-5f2e-4f5a-9e58-5b9c3c7d2a11",
  "vaultPath": "secret/data/login-alice",
  "fieldMap": {
    "username": "username",
    "password": "password",
    "totp": "totp_seed"
  },
  "allowedDomains": ["app.example.com", "*.internal.example.com"],
  "createdAt": "2026-04-24T09:12:44Z",
  "updatedAt": "2026-04-24T09:12:44Z"
}

​
Error Responses

StatusDescription
400Invalid body, unknown vaultIntegrationId, or disallowed domain pattern (for example *).
401Unauthorized — invalid or missing API key.