Sessions
A session represents an authorized session for a consumer. A session is a JWT token that is valid for a short time (1h by default). Use this session token to open Hosted Vault or Vault JS for a consumer.
The Sessions model
The metadata of the consumer. This is used to display the consumer in the sidebar. This is optional, but recommended.
The URL to redirect the user to after the session has been configured.
Settings to change the way the Vault is displayed.
Theming options to change the look and feel of Vault.
Custom consumer settings that are passed as part of the session.
Create Session
Making a POST request to this endpoint will initiate a Hosted Vault session. Redirect the consumer to the returned URL to allow temporary access to manage their integrations and settings.
Note: This is a short lived token that will expire after 1 hour (TTL: 3600).
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Additional redirect uri and/or consumer metadata
Request body schema
The metadata of the consumer. This is used to display the consumer in the sidebar. This is optional, but recommended.
The URL to redirect the user to after the session has been configured.
Settings to change the way the Vault is displayed.
Theming options to change the look and feel of Vault.
Custom consumer settings that are passed as part of the session.
Responses
Request example
Response example
Connections
A connection represents an account of a consumer for a connector. For example a consumer with ID "test-consumer" has a Salesforce connection for the CRM API. Connections securely save credentials and settings for a connector.
The Connections model
The unique identifier of the connection.
The ID of the service this connection belongs to.
The name of the connection
The unified API category where the connection belongs to.
Get all connections
This endpoint includes all the configured integrations and contains the required assets to build an integrations page where your users can install integrations. OAuth2 supported integrations will contain authorize and revoke links to handle the authentication flows.
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Query parameters
Scope results to Unified API
Scopes results to connections that have been configured or not
Responses
Request example
Response example
Get connection
Get a connection
Path parameters
Service ID of the resource to return
Unified API
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Responses
Request example
Response example
Create connectionNo SDK Support
Create an authorized connection
Path parameters
Service ID of the resource to return
Unified API
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Fields that need to be persisted on the resource
Request body schema
Whether the connection is enabled or not. You can enable or disable a connection using the Update Connection API.
Connection settings. Values will persist to form_fields with corresponding id
Attach your own consumer specific metadata
List of custom mappings configured for this connection
Responses
Request example
Response example
Update connection
Update a connection
Path parameters
Service ID of the resource to return
Unified API
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Fields that need to be updated on the resource
Request body schema
Whether the connection is enabled or not. You can enable or disable a connection using the Update Connection API.
Connection settings. Values will persist to form_fields with corresponding id
Attach your own consumer specific metadata
List of custom mappings configured for this connection
Responses
Request example
Response example
Deletes a connection
Deletes a connection
Path parameters
Service ID of the resource to return
Unified API
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Responses
Request example
Response example
Import connection
Import an authorized connection.
Path parameters
Service ID of the resource to return
Unified API
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Fields that need to be persisted on the resource
Request body schema
Connection settings. Values will persist to form_fields with corresponding id
Attach your own consumer specific metadata
Responses
Request example
Response example
Authorize Access Token
Triggers exchanging persisted connection credentials for an access token and store it in Vault. Currently supported for connections with the client_credentials or password OAuth grant type.
Note:
- Do not include any credentials in the request body. This operation does not persist changes, but only triggers the exchange of persisted connection credentials for an access token.
- The access token will not be returned in the response. A 200 response code indicates the authorization was successful and that a valid access token was stored on the connection.
- The access token will be used for subsequent API requests.
Path parameters
Service ID of the resource to return
Unified API
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Request body schema
Responses
Request example
Response example
Validate Connection State
This endpoint validates the current state of a given connection. This will perform different checks based on the connection auth type. For basic and apiKey auth types, the presence of required fields is checked. For connectors that implement OAuth2, this operation forces the refresh flow for an access token regardless of its expiry.
Note:
- Do not include any credentials in the request body. This operation does not persist changes, but only triggers the validation of connection state.
- If a refresh token flow was performed and successful, the new access token will then be used for subsequent API requests.
Path parameters
Service ID of the resource to return
Unified API
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Request body schema
Responses
Request example
Response example
Create Callback State
This endpoint creates a callback state that can be used to issue requests to the callback endpoint.
Path parameters
Service ID of the resource to return
Unified API
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Callback state data
Request body schema
The redirect URI to be used after the connection is created.
Responses
Request example
Response example
Get resource settings
This endpoint returns custom settings and their defaults required by connection for a given resource.
Path parameters
Unified API
Service ID of the resource to return
Name of the resource (plural)
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Responses
Request example
Response example
Update settings
Update default values for a connection's resource settings
Path parameters
Service ID of the resource to return
Unified API
Name of the resource (plural)
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Fields that need to be updated on the resource
Request body schema
Whether the connection is enabled or not. You can enable or disable a connection using the Update Connection API.
Connection settings. Values will persist to form_fields with corresponding id
Attach your own consumer specific metadata
List of custom mappings configured for this connection
Responses
Request example
Response example
Get resource custom fields
This endpoint returns an custom fields on a connection resource.
Path parameters
Unified API
Service ID of the resource to return
Name of the resource (plural)
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Query parameters
This is the id of the resource you want to fetch when listing custom fields. For example, if you want to fetch custom fields for a specific contact, you would use the contact id.
Responses
Request example
Response example
List connection custom mappings
This endpoint returns a list of custom mappings for a connection.
Path parameters
Unified API
Service ID of the resource to return
Name of the resource (plural)
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Query parameters
This is the id of the resource you want to fetch when listing custom fields. For example, if you want to fetch custom fields for a specific contact, you would use the contact id.
Responses
Request example
Response example
AuthorizeNo SDK Support
In most cases the authorize link is provided in the /connections endpoint. Normally you don't need to manually generate these links.
Use this endpoint to authenticate a user with a connector. It will return a 301 redirect to the downstream connector endpoints.
Auth links will have a state parameter included to verify the validity of the request. This is the url your users will use to activate OAuth supported integration providers.
Vault handles the complete Authorization Code Grant Type Flow for you and will redirect you to the dynamic redirect uri you have appended to the url in case this is missing the default redirect uri you have configured for your Unify application.
Path parameters
Service ID of the resource to return
Application ID of the resource to return
Query parameters
An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks.
URL to redirect back to after authorization. When left empty the default configured redirect uri will be used.
One or more OAuth scopes to request from the connector. OAuth scopes control the set of resources and operations that are allowed after authorization. Refer to the connector's documentation for the available scopes.
Responses
Response example
Revoke connectionNo SDK Support
In most cases the authorize link is provided in the /connections endpoint. Normally you don't need to manually generate these links.
Use this endpoint to revoke an existing OAuth connector.
Auth links will have a state parameter included to verify the validity of the request. This is the url your users will use to activate OAuth supported integration providers.
Vault handles the complete revoke flow for you and will redirect you to the dynamic redirect uri you have appended to the url.
Path parameters
Service ID of the resource to return
Application ID of the resource to return
Query parameters
An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks.
The redirect uri to redirect to after the revoke flow is completed.
Responses
Response example
CallbackNo SDK Support
This endpoint gets called after the triggering the authorize flow.
Callback links need a state and code parameter to verify the validity of the request.
Query parameters
An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks.
An authorization code from the connector which Apideck Vault will later exchange for an access token.
Responses
Response example
Consumers
A consumer represents an account or user in your system. All connections to connectors are scoped to a consumer.
The Consumers model
Unique consumer identifier. You can freely choose a consumer ID yourself. Most of the time, this is an ID of your internal data model that represents a user or account in your system (for example account:12345). If the consumer doesn't exist yet, Vault will upsert a consumer based on your ID.
ID of your Apideck Application
The metadata of the consumer. This is used to display the consumer in the sidebar. This is optional, but recommended.
Create consumer
Create a consumer
Header parameters
The ID of your Unify application
Request body schema
Unique consumer identifier. You can freely choose a consumer ID yourself. Most of the time, this is an ID of your internal data model that represents a user or account in your system (for example account:12345). If the consumer doesn't exist yet, Vault will upsert a consumer based on your ID.
The metadata of the consumer. This is used to display the consumer in the sidebar. This is optional, but recommended.
Responses
Request example
Response example
Get all consumers
This endpoint includes all application consumers, along with an aggregated count of requests made.
Header parameters
The ID of your Unify application
Query parameters
Cursor to start from. You can find cursors for next/previous pages in the meta.cursors property of the response.
Number of results to return. Minimum 1, Maximum 200, Default 20
Responses
Request example
Response example
Get consumer
Consumer detail including their aggregated counts with the connections they have authorized.
Path parameters
ID of the consumer to return
Header parameters
The ID of your Unify application
Responses
Request example
Response example
Update consumer
Update consumer metadata such as name and email.
Path parameters
ID of the consumer to return
Header parameters
The ID of your Unify application
Request body schema
The metadata of the consumer. This is used to display the consumer in the sidebar. This is optional, but recommended.
Responses
Request example
Response example
Delete consumer
Delete consumer and all their connections, including credentials.
Path parameters
ID of the consumer to return
Header parameters
The ID of your Unify application
Responses
Request example
Response example
Consumer request counts
Get consumer request counts within a given datetime range.
Path parameters
ID of the consumer to return
Header parameters
The ID of your Unify application
Query parameters
Scopes results to requests that happened after datetime
Scopes results to requests that happened before datetime
Responses
Request example
Response example
Logs
A log represents a request made for a given consumer. Logs include requests made to unified APIs, connectors and the Vault API.
The Logs model
Indicates if the request was made via REST or Graphql endpoint.
The Apideck base URL the request was made to.
Indicates whether or not this is a child or parent request.
The consumer Id associated with the request.
The entire execution time in milliseconds it took to call the Apideck service provider.
If error occurred, this is brief explanation
Get all consumer request logs
This endpoint includes all consumer request logs.
Header parameters
The ID of your Unify application
ID of the consumer which you want to get or push data from
Query parameters
Filter results
Cursor to start from. You can find cursors for next/previous pages in the meta.cursors property of the response.
Number of results to return. Minimum 1, Maximum 200, Default 20
Responses
Request example
Response example
Custom Mappings
A custom mapping represents a mapping between a connector and a Unified API. Custom mappings allow you to map downstream properties to the Unified API response.
The Custom Mappings model
Target Field ID
Target Field name to use as a label
Target Field description
Target Field Mapping value
Target Field Key
Target Field Mapping is required
List custom mappings
This endpoint returns a list of custom mappings.
Path parameters
Unified API
Service ID of the resource to return
Header parameters
ID of the consumer which you want to get or push data from
The ID of your Unify application
Responses
Request example
Response example
Connection CreatedWebhook
Event broadcast when a connection has been created.
Header parameters
The type of event that was triggered
An idempotency key is a unique value generated to recognize subsequent retries/duplicates of the same request.
Request body schema
Responses
Example Event
Connection UpdatedWebhook
Event broadcast when a connection has been updated.
Header parameters
The type of event that was triggered
An idempotency key is a unique value generated to recognize subsequent retries/duplicates of the same request.
Request body schema
Responses
Example Event
Connection DisabledWebhook
Event broadcast when a connection has been disabled.
Header parameters
The type of event that was triggered
An idempotency key is a unique value generated to recognize subsequent retries/duplicates of the same request.
Request body schema
Responses
Example Event
Connection DeletedWebhook
Event broadcast when a connection has been deleted.
Header parameters
The type of event that was triggered
An idempotency key is a unique value generated to recognize subsequent retries/duplicates of the same request.
Request body schema
Responses
Example Event
Connection CallableWebhook
Event broadcast when a connection is now callable.
Header parameters
The type of event that was triggered
An idempotency key is a unique value generated to recognize subsequent retries/duplicates of the same request.
Request body schema
Responses
Example Event
Connection RevokedWebhook
Event broadcast when a connection has been revoked.
Header parameters
The type of event that was triggered
An idempotency key is a unique value generated to recognize subsequent retries/duplicates of the same request.
Request body schema
Responses
Example Event
Connection Token Refresh FailedWebhook
Event broadcast when a connection token refresh has failed.
Header parameters
The type of event that was triggered
An idempotency key is a unique value generated to recognize subsequent retries/duplicates of the same request.
Request body schema
Responses
Example Event