thelastapi
Get started free

Import an OpenAPI spec and call it from your app or agent

Import an OpenAPI 3 spec using the vibiz CLI to turn any API into a secured connector your app or AI agent can call with one unified key.

On this page 7 sections

You can import an OpenAPI 3 specification into thelastapi using the CLI command vibiz connectors import <spec-url|file> --add. This parses the spec in JSON or YAML, lists its operations, flags any unsupported schemas, and registers the API directly to your project. Your application or agent can then invoke those endpoints through the @vibiz/app SDK or the command line while thelastapi stores the upstream credentials securely.

This guide walks through how to import an OpenAPI definition, seal upstream API keys, configure operational permissions, and execute calls safely from your code or AI agents.

Why import an OpenAPI spec into your project gateway

When you build applications or configure AI agents to interact with external services, handling individual API keys across environments is fragile. Keys end up scattered across developer laptops, CI pipelines, and agent prompts. Furthermore, giving an AI agent unrestricted access to raw HTTP credentials risks prompt injection, uncontrolled spend, or unintended destructive actions.

Importing an OpenAPI spec creates a managed connector. This provides three concrete advantages:

  • Key isolation: Your app or agent needs only one secret, VIBIZ_APP_KEY. Upstream API tokens remain sealed inside thelastapi and are injected into outgoing requests automatically. For more details on this architecture, see how to call your own APIs through one gateway, with their keys sealed.
  • Operation control: You can inspect endpoints, disable dangerous write actions, and require human approval before an agent executes production changes.
  • Unified stack: Custom endpoints sit alongside your database, email, AI gateway, and storage under one key for your whole app.

Connectors require no dedicated project resource provisioning. If you want a standalone connector setup for an existing system, you can initialize a project with --resources none as described in our guide on how to use just one service from an app hosted anywhere.

Step 1: Preview and import the OpenAPI specification

The vibiz connectors import command accepts an OpenAPI 3 specification from either a local file or a remote URL. It reads both JSON and YAML formats.

Running the command without the --add flag gives you a preview:

Terminal
vibiz connectors import https://api.example.com/openapi.json --name crm

The CLI inspects the document, displays the parsed operations with their HTTP methods and paths, and reports any parts of the specification that could not be parsed.

To register the connector to your project, add the --add flag. You can also specify the connector name and restrict enabled operations immediately:

Terminal
vibiz connectors import ./crm-spec.yaml --name crm --enable listUsers,getUser --add

Once saved, the endpoints become operations attached to the crm connector. You can check the current registered connectors at any time:

Terminal
vibiz connectors list

Step 2: Store API secrets without exposing them in chat

Before the connector can call the target API, it needs authentication credentials. thelastapi supports multiple authentication modes for connectors, including bearer tokens, header values, and query parameters.

To set the credential in production, an owner or a full-access key sets the secret:

Terminal
vibiz connectors secret crm CRM_API_KEY

The CLI reads the secret from your local $CRM_API_KEY environment variable or prompts for it in a hidden input field. The value is stored on the server and is never printed back to the terminal.

For development environments, pass --dev to supply sandbox credentials:

Terminal
vibiz connectors secret crm DEV_CRM_KEY --dev

If you are collaborating with an AI agent (such as Claude Code, Codex, or Cursor) using a Limited key, the agent cannot read or set production secrets directly. Instead, the agent requests a secret link. It generates a URL pointing to the console:

Text
Paste CRM_API_KEY here: https://thelastapi.dev/projects/prj_123/secrets/new?name=CRM_API_KEY&env=production&kind=connector . It goes straight to thelastapi, never through this chat.

The account owner pastes the key into the web interface. This ensures third-party API credentials never pass through an LLM chat log or agent context window. Read more on permission boundaries in Keys and environments.

Step 3: Inspect, enable, and test operations

Once the spec is imported and the credential is set, verify the available operations and their parameters:

Terminal
vibiz connectors ops crm

This lists all operations defined in the OpenAPI spec, showing parameter requirements, active status, and whether an action involves write risks.

You can enable or disable specific endpoints to maintain tight access boundaries:

Terminal
vibiz connectors enable crm createUser
vibiz connectors disable crm deleteUser

To confirm the upstream service accepts the credentials, run a health check:

Terminal
vibiz connectors check crm

You can execute a manual call from the terminal to ensure parameters and headers format properly:

Terminal
vibiz connectors call crm getUser id=usr_456

For endpoints expecting a JSON payload, supply the body as a JSON string:

Terminal
vibiz connectors call crm createUser --body '{"name":"Ana","email":"ana@example.com"}'

To review recent requests without exposing sensitive payload content, run:

Terminal
vibiz connectors logs crm

Step 4: Call the imported API from your code

Your application code calls connector operations through the @vibiz/app SDK. The SDK requires only VIBIZ_APP_KEY, which is available in your production environment or loaded locally via vibiz dev.

Install the SDK:

Terminal
npm install @vibiz/app

Then invoke operations by naming the connector, operation, and parameters:

TypeScript
import { vibiz } from '@vibiz/app';

// Read data
const user = await vibiz.connectors.call('crm', 'getUser', {
  params: { id: 'usr_456' },
});
console.log(user);

// Submit a body payload
const created = await vibiz.connectors.call('crm', 'createUser', {
  body: {
    name: 'Ana',
    email: 'ana@example.com',
  },
});
console.log(created);

If your application runtime cannot install dependencies, use standard HTTP fetch against the /v1/app endpoints:

TypeScript
const response = await fetch('https://thelastapi.dev/v1/app/connectors/crm/call', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIBIZ_APP_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    operation: 'getUser',
    params: { id: 'usr_456' },
  }),
});

const data = await response.json();

All responses returned from third-party connectors are treated strictly as external data. In AI-driven applications, this ensures payload text is never interpreted by default as system-level prompt instructions.

Guardrails for AI agents: Limited keys and human approvals

When automated coding agents make connector requests, you can control their blast radius using Limited API keys.

CapabilityLimited Key (access: agent)Full-Access Key (access: owner)
Import OpenAPI specAllowedAllowed
Run vibiz connectors checkAllowed in developmentAllowed
Read connector logsAllowedAllowed
Set production connector secretForbidden (generates secret link)Allowed
Production write operationsRequires human approvalExecuted immediately
Change connector settingsRequires connectors.live:writeAllowed

When an agent using a Limited key attempts a production write operation or triggers a sensitive action, the operation pauses. The agent receives an approval ID instead of executing blindly.

An account owner reviews and resolves pending approvals from the CLI:

Terminal
vibiz connectors approvals           # List waiting calls
vibiz connectors approve apr_789     # Allow the execution
vibiz connectors deny apr_789        # Reject the execution

If a Limited key lacks permissions to configure live connectors, the API returns 403 forbidden with owner_only, providing details.grant_url where the owner can grant connectors.live:write specifically for that key.

For complete SDK methods and routing patterns, refer to the @vibiz/app documentation and the full Connectors guide. Next, see how to call Claude and Gemini from the OpenAI Node.js SDK using the same environment key.

Frequently asked questions

What OpenAPI versions are supported by the import command?

The `vibiz connectors import` command supports OpenAPI 3 specifications in both JSON and YAML formats. It parses operations, paths, parameters, and request structures, and reports any unsupported schemas during preview.

Can an AI agent configure connector secrets directly?

No, an agent using a Limited key cannot view or write production credentials. Instead, it generates a secure web link using the API, allowing the project owner to paste the key directly into the console.

Where does the app find credentials to call the connector?

The application needs only `VIBIZ_APP_KEY`. thelastapi maintains the upstream API secret and injects it into outgoing requests at the gateway.