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
- Why import an OpenAPI spec into your project gateway
- Step 1: Preview and import the OpenAPI specification
- Step 2: Store API secrets without exposing them in chat
- Step 3: Inspect, enable, and test operations
- Step 4: Call the imported API from your code
- Guardrails for AI agents: Limited keys and human approvals
- FAQ
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:
vibiz connectors import https://api.example.com/openapi.json --name crmThe 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:
vibiz connectors import ./crm-spec.yaml --name crm --enable listUsers,getUser --addOnce saved, the endpoints become operations attached to the crm connector. You can check the current registered connectors at any time:
vibiz connectors listStep 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:
vibiz connectors secret crm CRM_API_KEYThe 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:
vibiz connectors secret crm DEV_CRM_KEY --devIf 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:
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:
vibiz connectors ops crmThis 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:
vibiz connectors enable crm createUser
vibiz connectors disable crm deleteUserTo confirm the upstream service accepts the credentials, run a health check:
vibiz connectors check crmYou can execute a manual call from the terminal to ensure parameters and headers format properly:
vibiz connectors call crm getUser id=usr_456For endpoints expecting a JSON payload, supply the body as a JSON string:
vibiz connectors call crm createUser --body '{"name":"Ana","email":"ana@example.com"}'To review recent requests without exposing sensitive payload content, run:
vibiz connectors logs crmStep 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:
npm install @vibiz/appThen invoke operations by naming the connector, operation, and parameters:
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:
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.
| Capability | Limited Key (access: agent) | Full-Access Key (access: owner) |
|---|---|---|
| Import OpenAPI spec | Allowed | Allowed |
Run vibiz connectors check | Allowed in development | Allowed |
| Read connector logs | Allowed | Allowed |
| Set production connector secret | Forbidden (generates secret link) | Allowed |
| Production write operations | Requires human approval | Executed immediately |
| Change connector settings | Requires connectors.live:write | Allowed |
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:
vibiz connectors approvals # List waiting calls
vibiz connectors approve apr_789 # Allow the execution
vibiz connectors deny apr_789 # Reject the executionIf 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.