Create Credential

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>"
  ]
}
'

import requests

url = "https://api.example.com/credentials"

payload = {
    "name": "<string>",
    "vaultIntegrationId": "<string>",
    "vaultPath": "<string>",
    "fieldMap": {
        "fieldMap.username": "<string>",
        "fieldMap.password": "<string>",
        "fieldMap.totp": "<string>"
    },
    "allowedDomains": ["<string>"]
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    vaultIntegrationId: '<string>',
    vaultPath: '<string>',
    fieldMap: {
      'fieldMap.username': '<string>',
      'fieldMap.password': '<string>',
      'fieldMap.totp': '<string>'
    },
    allowedDomains: ['<string>']
  })
};

fetch('https://api.example.com/credentials', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/credentials",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'vaultIntegrationId' => '<string>',
    'vaultPath' => '<string>',
    'fieldMap' => [
        'fieldMap.username' => '<string>',
        'fieldMap.password' => '<string>',
        'fieldMap.totp' => '<string>'
    ],
    'allowedDomains' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.example.com/credentials"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"vaultIntegrationId\": \"<string>\",\n  \"vaultPath\": \"<string>\",\n  \"fieldMap\": {\n    \"fieldMap.username\": \"<string>\",\n    \"fieldMap.password\": \"<string>\",\n    \"fieldMap.totp\": \"<string>\"\n  },\n  \"allowedDomains\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	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))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/credentials")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"vaultIntegrationId\": \"<string>\",\n  \"vaultPath\": \"<string>\",\n  \"fieldMap\": {\n    \"fieldMap.username\": \"<string>\",\n    \"fieldMap.password\": \"<string>\",\n    \"fieldMap.totp\": \"<string>\"\n  },\n  \"allowedDomains\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/credentials")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"vaultIntegrationId\": \"<string>\",\n  \"vaultPath\": \"<string>\",\n  \"fieldMap\": {\n    \"fieldMap.username\": \"<string>\",\n    \"fieldMap.password\": \"<string>\",\n    \"fieldMap.totp\": \"<string>\"\n  },\n  \"allowedDomains\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "name": "<string>",
  "vaultIntegrationId": "<string>",
  "vaultPath": "<string>",
  "fieldMap": {},
  "allowedDomains": [
    "<string>"
  ],
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

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>"
  ]
}
'

import requests

url = "https://api.example.com/credentials"

payload = {
    "name": "<string>",
    "vaultIntegrationId": "<string>",
    "vaultPath": "<string>",
    "fieldMap": {
        "fieldMap.username": "<string>",
        "fieldMap.password": "<string>",
        "fieldMap.totp": "<string>"
    },
    "allowedDomains": ["<string>"]
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    vaultIntegrationId: '<string>',
    vaultPath: '<string>',
    fieldMap: {
      'fieldMap.username': '<string>',
      'fieldMap.password': '<string>',
      'fieldMap.totp': '<string>'
    },
    allowedDomains: ['<string>']
  })
};

fetch('https://api.example.com/credentials', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/credentials",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'vaultIntegrationId' => '<string>',
    'vaultPath' => '<string>',
    'fieldMap' => [
        'fieldMap.username' => '<string>',
        'fieldMap.password' => '<string>',
        'fieldMap.totp' => '<string>'
    ],
    'allowedDomains' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.example.com/credentials"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"vaultIntegrationId\": \"<string>\",\n  \"vaultPath\": \"<string>\",\n  \"fieldMap\": {\n    \"fieldMap.username\": \"<string>\",\n    \"fieldMap.password\": \"<string>\",\n    \"fieldMap.totp\": \"<string>\"\n  },\n  \"allowedDomains\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	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))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/credentials")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"vaultIntegrationId\": \"<string>\",\n  \"vaultPath\": \"<string>\",\n  \"fieldMap\": {\n    \"fieldMap.username\": \"<string>\",\n    \"fieldMap.password\": \"<string>\",\n    \"fieldMap.totp\": \"<string>\"\n  },\n  \"allowedDomains\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/credentials")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"vaultIntegrationId\": \"<string>\",\n  \"vaultPath\": \"<string>\",\n  \"fieldMap\": {\n    \"fieldMap.username\": \"<string>\",\n    \"fieldMap.password\": \"<string>\",\n    \"fieldMap.totp\": \"<string>\"\n  },\n  \"allowedDomains\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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

string

required

Human-readable name. 1-100 characters.

string

required

UUID of the vault integration that will be used to read the secret. Created via POST /vault-integrations.

string

required

Path inside your vault. For HashiCorp KV v2 use the logical path (for example secret/data/login-alice).

object

required

Maps the field names stored inside the vault secret to the roles the authenticate action understands.

Show fieldMap properties

string

required

Vault field name that holds the username.

string

required

Vault field name that holds the password.

string

Optional vault field name for a TOTP seed (MFA).

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"]
  }'

const response = await fetch("https://api.scrapengine.io/api/v1/credentials", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCRAPENGINE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Alice @ app.example.com",
    vaultIntegrationId: "5f8c6a74-5f2e-4f5a-9e58-5b9c3c7d2a11",
    vaultPath: "secret/data/login-alice",
    fieldMap: { username: "username", password: "password" },
    allowedDomains: ["app.example.com"],
  }),
});
const data = await response.json();

import requests

response = requests.post(
    "https://api.scrapengine.io/api/v1/credentials",
    headers={
        "Authorization": f"Bearer {SCRAPENGINE_API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Alice @ app.example.com",
        "vaultIntegrationId": "5f8c6a74-5f2e-4f5a-9e58-5b9c3c7d2a11",
        "vaultPath": "secret/data/login-alice",
        "fieldMap": {"username": "username", "password": "password"},
        "allowedDomains": ["app.example.com"],
    },
)
data = response.json()

Response

Success Response (201)

string

Credential ID (UUID). Reference this from the authenticate task action.

string

The name you provided.

string

The vault integration this credential reads from.

string

The vault path this credential reads from.

object

The stored field-name mapping, echoed back.

string[]

The stored allow-list of hostnames, echoed back.

string

ISO 8601 timestamp.

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

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

API documentation

Web Scraping

Browser Sessions

Sessions

Tools

Tasks

AI

Recording

Extensions

Session Proxy

Clipboard

Filesystem

Session Files

Credentials & Vault

Search Engines

E-Commerce

Overview

Body

Example Request

Response

Success Response (201)

Error Responses

​Overview

​Body

​Example Request

​Response

​Success Response (201)

​Error Responses

Overview

Body

Example Request

Response

Success Response (201)

Error Responses