BR1N — Connect Your Project via API

This guide explains how to connect an existing project to BR1N using the BR1N API.

There are two distinct flows:

1. Project Import (read-only, metadata)
2. Event Ingestion (runtime signals)

They use the same API key, but serve different purposes.

1. Create a BR1N API Key

In the BR1N dashboard:

1. Go to Settings → API Keys
2. Generate a new key
3. Choose the environment:
   • test for development
   • live for production
4. Copy the key (it is only shown once)

Security rules

• Store the key server-side only
• Never expose it in frontend code
• Rotate keys if leaked

2. Project Import (Required)

Project import lets BR1N discover and visualize your project:

• workflows
• triggers
• tools
• connections

2.1 Implement the introspection endpoint

Your project must expose the following endpoint:

This endpoint returns metadata only.

2.2 Introspection response format (required)

{
  "project": {
    "id": "my-project-id",
    "name": "My Project",
    "environment": "production"
  },

  "tools": [
    { "key": "stripe" },
    { "key": "resend" },
    { "key": "supabase" }
  ],

  "connections": [
    {
      "external_id": "stripe_prod",
      "integration_key": "stripe",
      "metadata": {
        "account_id": "acct_123"
      }
    }
  ],

  "workflows": [
    {
      "external_id": "order_created_flow",
      "name": "Order Created",
      "triggers": [
        {
          "type": "webhook",
          "event_key": "order.created"
        }
      ],
      "steps": [
        {
          "integration": "resend",
          "function": "send_email"
        }
      ]
    }
  ]
}

Rules

• All IDs must be stable
• No secrets
• No API keys
• No OAuth tokens
• Metadata only

2.3 What BR1N does with this data

When you connect a project in BR1N:

1. BR1N calls /br1n/introspect
2. Creates an import session
3. Imports:
   • workflows as read-only
   • connections as external
4. Shows everything visually in the UI

3. Event Ingestion (Optional, Runtime)

Event ingestion lets your project notify BR1N that something happened.

This is how workflows get evaluated.

3.1 Send an event

{
  "event": "user.signup",
  "data": {
    "userId": "123",
    "email": "user@example.com"
  },
  "idempotencyKey": "optional-unique-key"
}

What happens

• Event is stored
• Matching workflows are evaluated
• Only explicitly enabled BR1N-managed steps can execute

External steps are never executed.

4. Hybrid Execution (Key Concept)

BR1N supports partial orchestration.

Example:

• Your project already sends emails
• You want BR1N to send SMS only

Flow:

1. Import project → everything is external
2. Convert only Twilio to a managed connection
3. Your project sends:

   { "event": "user.signup" }

4. BR1N:
   • Evaluates workflow
   • Skips external steps
   • Executes only Twilio

5. What BR1N Will Never Do

• Never pull provider secrets
• Never execute imported logic
• Never mutate your project
• Never require OAuth for imports
• Never guess your architecture

6. Common Setup Pattern

7. FAQ

Do I need to change my existing architecture?

No. You only add:

• one introspection endpoint
• optional event calls

Can I test this locally?

Yes.

• Use br1n_sk_test_…
• Point BR1N to your local or staging URL

Is BR1N replacing my backend?

No. BR1N is a control plane, not your runtime.

Can I send events without importing?

Yes, but you won't get visual workflows.

Import is strongly recommended.