Your organization likely relies on external tools and services that elvex doesn't natively support; a proprietary HRIS, an internal operations platform, a custom ecommerce backend. Without a way to connect these systems, your agents are limited to conversation alone. Custom API integrations solve this by letting you bring any external API into elvex, so your agents can take real action in the systems your team already uses, without building custom connectors from scratch.
You might need a custom API integration when:
A support agent needs to look up order status in your e-commerce platform
An HR agent needs to create or update employee records in your HRIS
A finance agent needs to pull invoice data from your accounting software
An operations agent needs to trigger jobs or pipelines in internal tooling
This guide will show you how to set up a custom API integration in elvex, configure authorization, and make those actions available to your agents as tools.
Before you begin
You must have an Admin or Owner company role to create or edit custom API integrations. If you don't see the option, contact your elvex administrator.
Have your API credentials ready — the type will depend on the authentication method you choose (see Authorization below).
How custom API integrations work
A custom API integration connects an external service to elvex by importing that service's OpenAPI schema. elvex reads the schema, interprets each endpoint, and uses an AI model to generate human-friendly action names — for example, turning POST /v1/invoices into Create Invoice. Those actions are then stored in elvex and can be enabled on any agent as tools the agent can call during a conversation.
Once an integration is set up, credentials are injected automatically at runtime. Agents never see raw API keys, tokens, or passwords — elvex handles credential management securely behind the scenes.
Setting up a custom API integration
In the elvex sidebar, navigate to Settings → Integrations.
Click Add, then select API.
Provide the OpenAPI schema for the service you want to connect (see Providing an OpenAPI schema below).
Give the integration a name that describes the service.
elvex parses the schema and displays a list of detected endpoints. Review the generated action names — you can rename any action if needed.
Configure your scope and authorization method (see Authorization below).
Click Save. Your actions are now available to be enabled on agents.
Providing an OpenAPI schema
elvex needs an OpenAPI schema to understand the endpoints your integration will use. There are three ways to provide one:
Paste the schema directly
If you already have the OpenAPI schema as a JSON file, you can paste it directly into the schema editor in the setup dialog.
Import from URL
If the service hosts its OpenAPI schema at a public URL (many APIs do), click Import from URL, enter the URL, and click Import. elvex will fetch and load the schema automatically — no need to download or copy anything.
Ask elvex
If the service doesn't have an OpenAPI schema, or you only have partial documentation, click Ask elvex to open an AI-assisted chat that can help you build one. You can:
Paste in text copied from the API's documentation pages
Point the AI to a URL it can scrape for endpoint information
Upload a PDF of private API documentation
The AI will generate an OpenAPI-compliant schema from whatever documentation you provide, which is then used to create the integration's actions. This is particularly useful for internal or proprietary APIs that don't publish a formal schema.
Authorization
When setting up a custom API integration, you'll choose two things: the scope (who shares credentials) and the authentication method (how those credentials work).
Scope
Global (company-wide)
A single set of credentials is shared across your entire organization. Any user interacting with an agent that uses this integration will use the same underlying credentials.
Use global scope when the integration accesses shared company resources that don't vary by user — for example, a company-wide inventory system or a shared data pipeline.
Per-user (each user connects separately)
Each user connects their own credentials to the integration. When a user interacts with an agent that uses this integration, their personal credentials are used for API calls. elvex will prompt each user to connect the first time they trigger a relevant action.
Use per-user scope when the integration accesses user-specific data — for example, a CRM where each salesperson has their own account and data.
Authentication methods
Both global and per-user scope support the following authentication methods:
None
The API does not require any authentication. No credentials are needed.
Bearer token
Standard bearer token authentication. Paste in the token and elvex will include it automatically as an Authorization: Bearer <token> header on every request.
Basic auth
Base64-encoded credentials. Paste in your encoded credentials and elvex will handle the rest.
Custom headers
Supply any number of custom key-value header pairs. Use this when an API requires non-standard headers that don't fit the other authentication methods — for example, a proprietary API key passed as X-API-Key.
OAuth 2.0
Both global and per-user scope also support OAuth 2.0. When OAuth is configured:
For global scope, the admin sets up the OAuth configuration once and all users share those credentials.
For per-user scope, the admin still configures the OAuth settings, but each user is redirected through their own OAuth login flow to connect their personal account.
elvex handles token management and refresh automatically — neither admins nor users need to manage tokens manually.
Advanced: OAuth 2.0 configuration
When configuring OAuth 2.0, you'll need to provide the following settings. These are supplied by the external service you're connecting to — check that service's developer documentation for the correct values.
Field | Description |
Authorization URL | The URL users are redirected to in order to grant access (e.g. |
Token URL | The endpoint elvex calls to exchange an authorization code for an access token (e.g. |
Client ID | The public identifier for your OAuth application, issued by the external service |
Client Secret | The private secret for your OAuth application, issued by the external service |
Scopes | A comma-separated list of OAuth permission scopes to request (e.g. |
Extra Authorization Parameters | Additional query parameters appended to the Authorization URL. Some providers require these — for example, Google requires |
Static Headers | Custom HTTP headers sent on every API request alongside the OAuth bearer token. Use this when the external service requires additional headers beyond standard OAuth authentication |
Enabling actions on an agent
Once your integration is saved, you can enable its actions on any agent.
Open the agent you want to configure.
Navigate to the agent's Tools settings.
Find your custom integration and toggle on the specific actions you want the agent to use.
Click Save.
How agents use custom API actions
When a user sends a message that requires information or an action from the external API, here's what happens:
The agent identifies the appropriate action to call based on the conversation.
elvex injects the correct credentials automatically — the agent never sees them.
The API call is made to the external service.
The response is returned to the agent.
The agent uses the response to generate a reply for the user.
Confirmation for write operations
elvex automatically applies a safeguard for actions that modify data, giving users the opportunity to review what the agent is about to do before it happens.
Read operations (GET requests): The agent can call these freely without interrupting the conversation.
Write operations (POST, PUT, DELETE): elvex will prompt the user to confirm before the action is executed.
This behavior is automatic and applies to all custom API integrations.
Next steps
Test your integration by enabling one or two actions on an agent and triggering them in a conversation to verify the connection is working as expected.
If you're using per-user scope, let your team know they'll be prompted to connect their credentials the first time they use the integration.
To update or rotate credentials, return to Settings → Integrations, find your custom integration, and edit it.
To learn more about how integrations work with agents, see How integration permissions and security work.