canonical: https://jentic.com/apis/apideck.com/vault # Apideck Vault API The Apideck Vault API manages connections, OAuth flows, consumer records, and custom field mappings that power every Apideck Unified API call. Thirty-one endpoints cover creating Vault sessions for end-user authorisation UIs, listing and configuring connections per consumer, importing pre-existing tokens, validating and refreshing connection state, and exposing logs for debugging. Custom-mappings endpoints let teams map their internal field IDs to each connector's native fields so Unified API payloads pass through correctly. Authentication uses the Apideck Authorization header alongside x-apideck-app-id; consumer IDs identify which end user a connection belongs to. ## For AI agents Manage OAuth connections, consumers, custom field mappings, and request logs that authorise every other Apideck Unified API call. ## Scope Does not call connector-native endpoints, manage end-user passwords, or run workflow logic - use only for OAuth connection lifecycle, consumers, custom mappings, and request logs. ## Capabilities - Create a Vault session URL via POST /vault/sessions for an end user to authorise a connection in-browser - List, create, get, update, and delete consumer records that scope connections to specific end users - Manage connections per consumer with /vault/connections/{unified_api}/{service_id} including update and delete - Import pre-existing OAuth tokens via POST /vault/connections/{unified_api}/{service_id}/import - Validate connection state and refresh access tokens with the /token and /validate sub-endpoints - List, create, get, update, and delete custom mappings between internal and connector-native field IDs - Pull request logs via GET /vault/logs and per-consumer request stats for debugging and usage tracking ## Use cases ### End-User OAuth via Hosted Vault Embed Apideck's hosted Vault UI into a SaaS product so end users can connect their own CRM, HRIS, or accounting system without the product building each OAuth flow itself. POST /vault/sessions returns a session URL that opens the Vault UI; the user picks a connector, completes OAuth, and the resulting connection is stored under their consumer ID. Subsequent Unified API calls use that consumer ID. Example prompt: Create a Vault session for consumer_id 'cust_42' scoped to the 'crm' Unified API, return the session URL, and store the consumer_id for subsequent CRM calls ### Connection Health Monitoring Detect broken connections before Unified API calls fail. POST /vault/connections/{unified_api}/{service_id}/validate checks whether the stored OAuth token is still valid and POST /vault/connections/{unified_api}/{service_id}/token forces a refresh. A scheduled job that runs validate over each connection lets a SaaS product proactively prompt users to re-authorise. Example prompt: List connections for consumer 'cust_42', call /validate on each, and for any that return inactive POST to /token to attempt refresh - then return the list of connections that still need user re-authorisation ### Custom Field Mapping Map an application's internal field IDs to each connector's native field names so Unified API payloads work correctly across customers using different CRMs. POST /vault/custom-mappings/{unified_api}/{service_id}/{target_field_id} creates a mapping; GET lists existing mappings; PATCH and DELETE manage updates and removals. Necessary for products that need to round-trip vendor-specific data through unified calls. Example prompt: For consumer 'cust_42' on the 'crm' Unified API, list custom mappings, then POST a new mapping for target_field_id 'lead_score' to the connector-native field ID provided in the input ### AI Agent Connection Management via Jentic An AI agent helps a customer connect their CRM and then troubleshoots failures. Through Jentic, the agent searches 'create a vault session' to start the OAuth flow, then 'list vault logs' to inspect request failures. Jentic stores the Apideck Authorization and x-apideck-app-id values separately so the agent never holds raw credentials, even while debugging connection state. Example prompt: Through Jentic, create a Vault session for the customer, return the URL, and after they authorise call /validate on the new connection to confirm it is active ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /vault/sessions | Create a Vault session URL for end-user OAuth | | GET | /vault/connections | List all connections | | POST | /vault/connections/{unified_api}/{service_id} | Create a connection | | POST | /vault/connections/{unified_api}/{service_id}/validate | Validate a connection's state | | POST | /vault/connections/{unified_api}/{service_id}/token | Refresh the access token for a connection | | POST | /vault/consumers | Create a consumer | | GET | /vault/logs | List recent request logs for debugging | | POST | /vault/custom-mappings/{unified_api}/{service_id}/{target_field_id} | Create a custom field mapping | ## Key resources - **Sessions** — Create a Vault session URL that hosts the OAuth flow for an end user - **Connections** — List, get, create, update, delete, import, validate, and refresh connections per consumer per service - **Consumers** — List, create, get, update, delete consumers and view their request stats - **Logs** — Read recent API request logs for debugging and audit - **Custom Mappings** — List, create, get, update, delete mappings between internal field IDs and connector-native fields ## Why Jentic - **Setup:** Wiring the Apideck Vault API by hand means setting up its API key headers, learning the connection and consumer shapes, and managing OAuth connection lifecycle yourself. Through Jentic you install once, import Apideck Vault from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** The Apideck Vault API puts the unified_api and service_id in the URL path (/vault/connections/{unified_api}/{service_id}/...), so a rule can pin your agent to one connection: it can validate and fetch a token for that connection and nothing else. You choose the operations it may call, so creating consumers is not included unless you add it. - **Credential handling:** Your Apideck API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list connections' or 'validate a connector connection', and Jentic returns the matching Apideck Vault operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Apideck Proxy API** — Proxy reuses the OAuth tokens stored by Vault to forward requests to connector-native endpoints. - **Apideck CRM Unified API** — Every CRM Unified API call requires a Vault-managed connection identified by consumer ID. - **Pipedream Connect** — Pipedream Connect provides a similar managed-OAuth and connection layer with workflow execution baked in. ## FAQ ### What authentication does the Apideck Vault API use? An apiKey scheme on the `Authorization` header with your Apideck application key, plus the `x-apideck-app-id` header. The `x-apideck-consumer-id` scopes operations to a specific end user. Through Jentic these values are stored encrypted in the vault and injected at execution time. ### Can I import an existing OAuth token instead of running a new authorisation flow? Yes. POST /vault/connections/{unified_api}/{service_id}/import takes an access token, refresh token, and metadata for an existing connection and stores it as if Vault had run the OAuth flow itself. Useful when migrating from a custom integration to Apideck. ### What are the rate limits for the Apideck Vault API? The OpenAPI spec does not publish per-endpoint rate limits. Apideck applies plan-based limits at unify.apideck.com - Vault calls (sessions, connections, custom mappings) count toward the same gateway quota as Unified API calls. See https://developers.apideck.com for your plan's numbers. ### How do I create a Vault session through Jentic? Install with `pip install jentic`, then run the search query 'create a vault session'. Jentic returns POST /vault/sessions - load its schema, supply consumer_id and the Unified APIs to scope the session to, then execute. The response includes a URL you redirect the end user to. ### How do I detect that a user's connection has expired? Call POST /vault/connections/{unified_api}/{service_id}/validate. If it reports the connection is no longer active, call POST /vault/connections/{unified_api}/{service_id}/token to attempt a refresh. If refresh fails, prompt the user to re-authorise via a fresh Vault session. ### What are custom mappings used for in this API? Custom mappings translate between the internal field IDs your product uses and each connector's native field ID. For example, your 'lead_score' might map to a custom Salesforce property - POST /vault/custom-mappings/{unified_api}/{service_id}/{target_field_id} stores the mapping so subsequent Unified API calls round-trip the value correctly. ### Can I limit what my agent is allowed to do with the Apideck Vault API? Yes. Because your Jentic One instance is self-hosted, your own rules decide which Vault operations and credentials the agent may use. The Apideck Vault API puts the unified_api and service_id in the URL path, so you can pin the agent to a single connection and let it only validate that connection and refresh its token via /vault/connections/{unified_api}/{service_id}/validate and /token. Operations are opt-in, so higher-impact calls like creating consumers or deleting connections are excluded unless you explicitly allow them.