# White-labeling authentication (/docs/white-labeling-authentication)

White-labeling lets you use your own OAuth apps instead of Devcaster's. Users will see your app name on consent screens instead of "Devcaster".

By default, OAuth screens show Devcaster's branding. With white-labeling, they'll see your app name and logo.

#### Create an OAuth app

Create a developer app in the toolkit's developer portal. You'll need the client ID and client secret. Set the callback URL to:

```
https://backend.devcaster.dev/api/v3/toolkits/auth/callback
```

> For step-by-step guides on creating OAuth apps for some toolkits, see [devcaster.dev/auth](https://devcaster.dev/auth).

#### Create auth config

Create an auth config in the [Devcaster dashboard](https://platform.devcaster.dev):

    1. Go to **Authentication management** → **Create Auth Config**
    2. Select the toolkit (e.g., GitHub)
    3. Choose **OAuth2** scheme
    4. Enter your **Client ID** and **Client Secret**
    5. Select the scopes you need
    6. Click **Create**

Copy the auth config ID (e.g., `ac_1234abcd`).

> For detailed instructions with screenshots, see [Custom auth configs](/docs/auth-configuration/custom-auth-configs).

#### Use in your session

Pass your auth config ID in the session:

**Python:**

```python
session = devcaster.create(
    user_id="user_123",
    auth_configs={
        "github": "ac_your_github_config"
    },
)
```

**TypeScript:**

```typescript
import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
const session = await devcaster.create("user_123", {
  authConfigs: {
    github: "ac_your_github_config",
  },
});
```

When users connect GitHub, they'll see your OAuth app's name and logo on the consent screen.

Mixing custom and Devcaster-managed auth [#mixing-custom-and-devcaster-managed-auth]

You can white-label some toolkits while using Devcaster's managed credentials for others:

**Python:**

```python
session = devcaster.create(
    user_id="user_123",
    auth_configs={
        "github": "ac_your_github_config",
        "slack": "ac_your_slack_config",
        # gmail, linear, etc. use Devcaster managed auth
    },
)
```

**TypeScript:**

```typescript
import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
const session = await devcaster.create("user_123", {
  authConfigs: {
    github: "ac_your_github_config",
    slack: "ac_your_slack_config",
    // gmail, linear, etc. use Devcaster managed auth
  },
});
```

Custom redirect domain [#custom-redirect-domain]

When users authenticate, they briefly see `backend.devcaster.dev` in their browser URL. Devcaster needs to receive the OAuth callback to capture and store the authentication tokens.

If you need to hide this URL (for enterprise compliance or complete white-labeling), you can proxy the redirect through your own domain:

1. Set your OAuth app's redirect URI to your domain:

```
https://yourdomain.com/api/devcaster-redirect
```

2. Create an endpoint that forwards the OAuth callback to Devcaster:

**Python:**

```python
from fastapi import FastAPI, Request
from fastapi.responses import RedirectResponse

app = FastAPI()

@app.get("/api/devcaster-redirect")
def devcaster_redirect(request: Request):
    # Forward all OAuth parameters to Devcaster
    devcaster_url = "https://backend.devcaster.dev/api/v3/toolkits/auth/callback"
    return RedirectResponse(url=f"{devcaster_url}?{request.url.query}")
```

**TypeScript:**

```typescript
// pages/api/devcaster-redirect.ts (Next.js)
import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  // Forward all OAuth parameters to Devcaster
  const devcasterUrl = "https://backend.devcaster.dev/api/v3/toolkits/auth/callback";
  const params = new URLSearchParams(req.query as Record<string, string>);
  res.redirect(302, `${devcasterUrl}?${params.toString()}`);

```

3. Update your auth config in the Devcaster dashboard to use your custom redirect URI.

This makes the OAuth flow go through your domain first, then to Devcaster for token storage.

---

📚 **More documentation:** [View all docs](https://docs.devcaster.dev/llms.txt) | [Cookbooks](https://docs.devcaster.dev/llms.mdx/cookbooks) | [API Reference](https://docs.devcaster.dev/llms.mdx/reference)

---

# Devcaster SDK — Instructions for AI Code Generators

**Purpose:** Enforce only the **current** and **correct** patterns for integrating [Devcaster](https://devcaster.dev/) tools into AI agents.
**Scope:** All AI-generated code using Devcaster must follow these guardrails.

---

## 1. Correct Devcaster Integration

Devcaster supports two integration modes: **Native Tools** (with a provider package) and **MCP** (no provider package needed).

### Native Tools

```python
# ✅ CORRECT — Python (defaults to OpenAI)
from devcaster import Devcaster

devcaster = Devcaster()
session = devcaster.create(user_id="user_123")
tools = session.tools()
# Pass tools to your agent/LLM framework
```

```typescript
// ✅ CORRECT — TypeScript (defaults to OpenAI)
import { Devcaster } from "@devcaster/core";

const devcaster = new Devcaster();
const session = await devcaster.create("user_123");
const tools = await session.tools();
// Pass tools to your agent/LLM framework
```

For other providers, pass the provider explicitly. Provider packages follow the naming convention: `devcaster_<provider>` for Python, `@devcaster/<provider>` for TypeScript.

### MCP

Use `session.mcp.url` and `session.mcp.headers` with any MCP-compatible client (Claude Desktop, Cursor, OpenAI Agents, etc.). No provider package needed.

---

## 2. CRITICAL INSTRUCTIONS FOR AI MODELS

### 2.1 — ALWAYS DO THE FOLLOWING

1. **Use `devcaster.create(user_id)`** to create a session — this is the entry point for all Devcaster integrations.
2. **Use `session.tools()`** for native tool integration or **`session.mcp.url`** for MCP integration.
3. **Import** from the correct provider package (`devcaster_<provider>` for Python, `@devcaster/<provider>` for TypeScript).
4. **Pass `user_id` to `devcaster.create()`**, not to individual tool calls.

### 2.2 — NEVER DO THE FOLLOWING

1. **Do not** instruct users to manually create auth configs or connected accounts before running.
2. **Do not** import from `devcaster_openai` / `@devcaster/openai` when using OpenAI Agents SDK — use `devcaster_openai_agents` / `@devcaster/openai-agents` instead.

### 2.3 — DISCOURAGED (do not use unless user explicitly asks)

Do **not** generate `devcaster.tools.get()`, `devcaster.tools.execute()`, or `devcaster.provider.handle_tool_calls()` unless the user explicitly requests direct tool execution. These are a supported but **not recommended** low-level interface.

