Integrate with your product

Add AI Gateway to your product as an integrations flow:

your settings page → customer connects a provider → your backend sends model requests

Alien stores the provider credentials. Your frontend only opens setup and displays connection status; model requests come from your backend.

1. Choose an external ID

An externalId is your stable identifier for a customer or tenant, such as org_123. Alien uses it to connect three things:

• the setup link you give that customer;
• the provider connection shown in your integrations UI; and
• model requests made on that customer's behalf.

Use an immutable database ID, not a display name or a value supplied by the browser. Resolve it from the authenticated customer on your backend.

2. Configure the models you offer

In Infrastructure → Models, select the models your product may call and the client APIs it uses. Alien shows customers the providers that can serve that configuration.

A required model must be available before setup is complete. Optional models do not block setup. For example:

alien projects capabilities enable ai \
  --model byo/claude-opus-5

3. Add a Connect button

When the customer clicks Connect AI provider, create a setup link on your backend and redirect them to deploymentLink.

import { Alien } from "@alienplatform/platform-api"

const alien = new Alien({ apiKey: process.env.ALIEN_API_KEY })

const setup = await alien.setupLinks.create({
  project: "my-project",
  externalId: customer.id,
  name: customer.slug,
  setupItems: [{ item: "models", required: true }],
})

return setup.deploymentLink

Calling this endpoint again with the same project and externalId reuses the customer record and returns a fresh link. Create links when the customer clicks Connect or Reconnect, not while rendering the page.

Open a specific provider

For a single Connect AI provider button, omit entryPoint and let the customer choose. If your UI has one card per provider, you can open that provider first:

const setup = await alien.setupLinks.create({
  project: "my-project",
  externalId: customer.id,
  name: customer.slug,
  setupItems: [{ item: "models", required: true }],
  entryPoint: { item: "models", provider: "databricks" },
})

The customer can still go back and choose another compatible provider. entryPoint controls the first screen, not what they are allowed to use.

Only add a policy when your product must prevent a choice. For example, this opens Databricks and permits only Databricks:

{
  "deploymentSetupConfig": {
    "policy": {"allowedAIProviders": ["databricks"]}
  },
  "entryPoint": {"item": "models", "provider": "databricks"}
}

Omit deploymentSetupConfig for the normal flow. See Setup Links API for advanced restrictions.

4. Send a model request

After the customer connects a provider, send requests through AI Gateway with the same customer ID in X-Alien-External-ID:

import OpenAI from "openai"

const ai = new OpenAI({
  baseURL: "https://ai.alien.dev/v1",
  apiKey: process.env.ALIEN_AI_KEY,
  defaultHeaders: {
    "X-Alien-External-ID": customer.id,
  },
})

const response = await ai.chat.completions.create({
  model: "byo/claude-opus-5",
  messages: [{ role: "user", content: "Hello" }],
})

The AI Gateway key identifies your project. X-Alien-External-ID selects the customer connection, and model selects a model available through it. Keep both the gateway key and the external ID decision on your backend. See Routing requests for other protocols and routing behavior.

5. Show connection status

Read the capability overview from your backend and find the record with the same externalId:

const overview = await alien.projects.getCapabilityOverview({
  idOrName: "my-project",
})

const group = overview.groups.find(
  group => group.externalId === customer.id,
)

const models = group?.capabilities.models
const provider = models?.directProvider?.provider ?? models?.observation?.provider

Use models.state as the top-level UI state:

modelCoverage shows which configured models are available, blocked, or not checked yet. A connected provider does not guarantee access to every model because regions, model activation, and quotas can differ.

The REST equivalent is:

curl --fail-with-body \
  "https://api.alien.dev/v1/projects/my-project/project-capabilities/overview?workspace=my-workspace" \
  -H "Authorization: Bearer $ALIEN_API_KEY"

6. Reconnect, change, or disconnect

To reconnect or change providers, create another setup link with the same externalId. The customer can resume incomplete cloud setup, replace a direct provider credential, or choose another available provider.

For OpenAI, Anthropic, and Databricks, remove the stored credential through setup or from your backend:

await alien.deploymentGroups.deleteExternalAIBinding({
  id: group.deploymentGroupId,
})

curl --fail-with-body -X DELETE \
  "https://api.alien.dev/v1/deployment-groups/dg_123/ai/external?workspace=my-workspace" \
  -H "Authorization: Bearer $ALIEN_API_KEY"

Bedrock, Vertex AI, and Azure AI Foundry use infrastructure in the customer's cloud account. The customer disconnects them by returning to setup and deleting the cloud stack or resources. Continue reading the capability overview until the state becomes revoked.

Gateway replicas may finish requests already admitted under a lease of up to five minutes.

Test the complete flow

For every provider you offer:

1. connect an account you control and confirm the state reaches connected;
2. call every required model through every client API your product uses;
3. test streaming and tool calls when applicable;
4. revoke access and confirm your UI reports the failure; and
5. reconnect and confirm requests recover.

Model protocols do not map perfectly. AI Gateway rejects cross-protocol fields it cannot represent instead of silently dropping them.