> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vybe.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom APIs

> Store API credentials securely in Vybe for services without a built-in integration

For services that do not have a built-in integration, you can store API credentials as a Custom API in Vybe. This gives your apps secure access to any REST API — and gives the AI context about the service so it can generate the right code.

***

## When to use Custom APIs

Use Custom APIs when:

* The service you need is not in the [integrations catalog](/integrations/all-integrations)
* You have an internal API that your apps need to call
* You want to manage API credentials centrally instead of hardcoding them
* You need the AI to understand how to call a specific API

Custom APIs store your credentials securely and inject them as environment variables into your app's server-side code.

***

## Authentication types

Custom APIs support three authentication methods:

| Type             | Header format                            | Use case                                           |
| ---------------- | ---------------------------------------- | -------------------------------------------------- |
| **API Key**      | `X-API-Key: sk_123abc`                   | Services that use a single API key                 |
| **Bearer Token** | `Authorization: Bearer token123`         | OAuth tokens, JWT tokens, or similar               |
| **Basic Auth**   | `Authorization: Basic base64(user:pass)` | Services that use username/password authentication |

Choose the type that matches how the target API expects to receive credentials.

***

## Creating a Custom API

<Steps>
  <Step title="Open the Integrations page">
    Navigate to **Integrations** in the left sidebar and scroll to the **Custom APIs** section.
  </Step>

  <Step title="Click Create Custom API">
    Click **Create Custom API** to open the creation form.
  </Step>

  <Step title="Enter the details">
    Fill in the following fields:

    | Field                 | Required | Description                                                                 |
    | --------------------- | -------- | --------------------------------------------------------------------------- |
    | **Name**              | Yes      | A descriptive name for the API (e.g., "Internal Billing API", "Twilio SMS") |
    | **Auth type**         | Yes      | API Key, Bearer Token, or Basic Auth                                        |
    | **Credentials**       | Yes      | The actual key, token, or username/password                                 |
    | **Domain**            | No       | Associate the API with a specific domain (e.g., `api.example.com`)          |
    | **Documentation URL** | No       | Link to the API's documentation so the AI can reference it                  |
  </Step>

  <Step title="Choose the scope">
    Select who can use this Custom API:

    * **Organization** — Available to all members and all apps in your workspace
    * **App-specific** — Available only to a specific app
  </Step>

  <Step title="Save">
    Click **Save**. The credentials are encrypted and stored securely. After saving, credential values are masked in the UI and cannot be viewed again.
  </Step>
</Steps>

***

## Environment variable injection

Each Custom API automatically gets an environment variable name based on the API name. For example:

| Custom API name       | Environment variable               |
| --------------------- | ---------------------------------- |
| My Billing API        | `CUSTOM_API_MY_BILLING_API`        |
| Twilio SMS            | `CUSTOM_API_TWILIO_SMS`            |
| Internal Auth Service | `CUSTOM_API_INTERNAL_AUTH_SERVICE` |

The variable contains the credential value (API key, bearer token, or base64-encoded basic auth string).

***

## Using Custom APIs in code

Access your Custom API credentials through environment variables in server-side code. The AI generates code like this when it knows about your Custom API:

```typescript theme={null}
export async function GET() {
  const response = await fetch('https://api.example.com/data', {
    headers: {
      'Authorization': `Bearer ${process.env.CUSTOM_API_MY_SERVICE}`,
      'Content-Type': 'application/json',
    },
  });

  const data = await response.json();
  return Response.json(data);
}
```

<Warning>
  Custom API credentials are only available in server-side code (API routes and server components). They are never exposed to the browser.
</Warning>

***

## Associating documentation

You can link API documentation to a Custom API so the AI can reference it when building features. This is particularly useful for complex APIs with many endpoints.

When you provide a documentation URL:

* The AI reads the documentation to understand the available endpoints, request formats, and response structures
* The AI generates more accurate code because it knows the exact API contract
* You spend less time correcting the AI's assumptions about the API

<Tip>
  If the API has an OpenAPI/Swagger spec, consider using [OpenAPI Client Generation](/integrations/openapi-client) instead for fully typed access.
</Tip>

***

## Security

Custom API credentials are protected with several security measures:

* **Encrypted at rest** — Credentials are encrypted before being stored in the database
* **Masked in the UI** — After creation, credential values are hidden and cannot be retrieved through the interface
* **Server-side only** — Credentials are injected as server-side environment variables and never sent to the browser
* **Scoped access** — Organization-scoped APIs are available to all workspace members; app-specific APIs are restricted to a single app

***

## Managing Custom APIs

From the Custom APIs section on the Integrations page, you can:

* **Edit** — Update the name, domain, documentation URL, or scope. To change credentials, delete and recreate the Custom API.
* **Delete** — Remove the Custom API. Apps that reference the environment variable will lose access to the credentials.
* **View** — See the API name, type, scope, and associated domain. Credential values are always masked.

<Note>
  If you need to rotate credentials, delete the existing Custom API and create a new one with the updated credentials. The environment variable name will remain the same if you use the same API name.
</Note>