Create Integration

Overview

Creates a node-scoped integration (API key + secret). The secret is returned only once during creation — store it securely. The API key and secret are immutable after creation.

Endpoint: POST /api/v1/integrations

Authentication: Bearer token (JWT) required.

---

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer <your_jwt_token>
Content-Type	Yes	application/json

Body

Field	Type	Required	Validation	Description
node_id	string	Yes	UUID	Node UUID that the integration belongs to
name	string	Yes	1–255 characters	Display name for the integration
permissions	string[]	No	—	Permission list (e.g. payments.read, payments.create)
expires_at	string	No	ISO 8601 datetime	Optional expiration date/time

Example Request

{
  "node_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production API",
  "permissions": ["payments.read", "payments.create"],
  "expires_at": "2026-12-31T23:59:59Z"
}

---

Response

Success — 201 Created

Field	Type	Description
id	string	Integration UUID
node_id	string	Node UUID
name	string	Integration name
api_key	string	API key (e.g. apex_abc123...)
secret	string	Plain secret — returned only on create
permissions	string[]	Permission list
expires_at	string	Expiration date (or null)
created_at	string	Creation timestamp

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "node_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production API",
  "api_key": "apex_abc123xyz456",
  "secret": "plain_secret_returned_only_once",
  "permissions": ["payments.read", "payments.create"],
  "expires_at": "2026-12-31T23:59:59Z",
  "created_at": "2025-02-14T10:00:00Z"
}

---

Error Responses

Status	Description
400	Invalid request (validation error)
401	Unauthorized (missing or invalid token)
404	Node not found
409	API key already exists for this node
500	Internal server error

---

cURL Example

curl -X POST https://api.example.com/api/v1/integrations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production API",
    "permissions": ["payments.read", "payments.create"]
  }'