Create a custom identifier

Create a custom identifier. This action uses the same domain service from REST and MCP, so successful calls produce the same canonical domain result.

Authorization and availability

Required scope: custom_identifiers:write. Available in Test and Live. REST operation: POST /v1/custom-identifiers. Equivalent MCP tool: veltor_register_custom_identifier.

Request schema

Unknown fields are rejected. Path values shown in the route are combined with the JSON body or query input before validation.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]{0,63}$"
    },
    "key_version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[\\x21-\\x7e]+$"
    },
    "description": {
      "type": "string",
      "minLength": 3,
      "maxLength": 200
    }
  },
  "required": [
    "key",
    "key_version",
    "description"
  ],
  "additionalProperties": false
}

Example request payload

{
  "key": "license_id",
  "key_version": "v1",
  "description": "Stable customer license identifier"
}

Response schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "propertyNames": {
    "type": "string"
  },
  "additionalProperties": {}
}

Example success response

REST returns this canonical domain result as JSON. MCP returns the same value in structuredContent and adds only its transport request ID.

{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "available"
}

Errors and recovery

Relevant errors include invalid input (422), missing scope or organization access (403), missing resources (404), revision or idempotency conflicts (409), rate limits (429), and deadline exhaustion (504). Use the returned request ID when investigating a failure.

Idempotency, retries, and timeout

Send a stable idempotency key and reuse it only for an exact retry of this mutation. The server deadline is 5 seconds. Retry only when the error reports retryable true.

cURL

curl -X POST https://veltor.dev/v1/custom-identifiers \
  -H "Authorization: Bearer $VELTOR_SECRET_KEY" \
  -H "Veltor-Organization: $VELTOR_ORGANIZATION" \
  -H "Idempotency-Key: operation_123" \
  -H "Content-Type: application/json" \
  --data '{"key":"license_id","key_version":"v1","description":"Stable customer license identifier"}'

Node SDK

const result = await veltor.call("/v1/custom-identifiers", {
  method: "POST",
  input: {"key":"license_id","key_version":"v1","description":"Stable customer license identifier"},
  idempotencyKey: "operation_123",
});

MCP

veltor_register_custom_identifier({
  "key": "license_id",
  "key_version": "v1",
  "description": "Stable customer license identifier",
  "idempotency_key": "operation_123"
})